dayjs の使い方 — 2KBの軽量日付操作ライブラリ完全ガイド

一言でいうと

dayjs は、Moment.js とほぼ同じAPIを持ちながら、わずか2KBという超軽量な日付操作ライブラリです。イミュータブル設計で、日付のパース・バリデーション・操作・フォーマットを安全かつ直感的に行えます。

どんな時に使う？

• 日付のフォーマット表示 — APIから受け取った日時を 2024年1月15日 や 2024-01-15 09:30 のような形式で画面に表示したいとき
• 日付の計算・比較 — 「3日後」「先月の月初」「この日付は期限内か？」といった日付演算が必要なとき
• Moment.js からの移行 — Moment.js のバンドルサイズ（約70KB gzip）が問題になり、軽量な代替を探しているとき

インストール

# npm
npm install dayjs

# yarn
yarn add dayjs

# pnpm
pnpm add dayjs

型定義は本体に同梱されているため、@types/dayjs の追加インストールは不要です。

基本的な使い方

import dayjs from 'dayjs';

// 現在日時
const now = dayjs();
console.log(now.format('YYYY-MM-DD HH:mm:ss'));
// => "2024-01-15 14:30:00"

// 文字列からパース
const date = dayjs('2024-03-01');

// 日付の操作（イミュータブル — 元のオブジェクトは変更されない）
const nextWeek = now.add(7, 'day');
const startOfMonth = now.startOf('month');

// メソッドチェーン
const result = dayjs()
  .startOf('month')
  .add(1, 'day')
  .set('year', 2025)
  .format('YYYY-MM-DD HH:mm:ss');
// => "2025-01-02 00:00:00"

// 比較
const deadline = dayjs('2024-12-31');
console.log(now.isBefore(deadline)); // => true

よく使うAPI

1. format() — 日付のフォーマット

import dayjs from 'dayjs';

const d = dayjs('2024-07-15T09:05:30');

d.format('YYYY/MM/DD');          // "2024/07/15"
d.format('YYYY年M月D日');         // "2024年7月15日"
d.format('HH:mm:ss');            // "09:05:30"
d.format('YYYY-MM-DDTHH:mm:ssZ'); // ISO 8601 風

// フォーマットトークン一覧（主要なもの）
// YYYY: 4桁年, MM: 2桁月, DD: 2桁日
// HH: 24時間制時, mm: 分, ss: 秒
// d: 曜日(0-6), A: AM/PM

2. add() / subtract() — 日付の加算・減算

import dayjs from 'dayjs';

const base = dayjs('2024-01-15');

// 加算
base.add(1, 'year').format('YYYY-MM-DD');   // "2025-01-15"
base.add(3, 'month').format('YYYY-MM-DD');  // "2024-04-15"
base.add(7, 'day').format('YYYY-MM-DD');    // "2024-01-22"
base.add(2, 'hour').format('HH:mm');        // "02:00"

// 減算
base.subtract(1, 'month').format('YYYY-MM-DD'); // "2023-12-15"

// イミュータブルなので元のオブジェクトは変わらない
console.log(base.format('YYYY-MM-DD')); // "2024-01-15"（そのまま）

3. startOf() / endOf() — 期間の先頭・末尾

import dayjs from 'dayjs';

const d = dayjs('2024-07-15T14:30:45');

d.startOf('year').format('YYYY-MM-DD HH:mm:ss');
// "2024-01-01 00:00:00"

d.startOf('month').format('YYYY-MM-DD HH:mm:ss');
// "2024-07-01 00:00:00"

d.endOf('month').format('YYYY-MM-DD HH:mm:ss');
// "2024-07-31 23:59:59"

d.startOf('day').format('YYYY-MM-DD HH:mm:ss');
// "2024-07-15 00:00:00"

// 週の先頭（デフォルトは日曜始まり）
d.startOf('week').format('YYYY-MM-DD');
// "2024-07-14"（日曜日）

4. isBefore() / isAfter() / isSame() — 日付の比較

import dayjs from 'dayjs';

const a = dayjs('2024-01-15');
const b = dayjs('2024-06-01');

a.isBefore(b);            // true
a.isAfter(b);             // false
a.isSame(b);              // false

// 単位を指定して比較（月単位で同じか？）
a.isSame(dayjs('2024-01-31'), 'month'); // true（同じ1月）
a.isBefore(b, 'year');                  // false（同じ2024年）

// バリデーション
dayjs('invalid-date').isValid(); // false
dayjs('2024-01-15').isValid();   // true

5. get() / set() — 値の取得・設定

import dayjs from 'dayjs';

const d = dayjs('2024-07-15T14:30:00');

// 取得
d.year();    // 2024
d.month();   // 6（0始まり！ 0=1月, 6=7月）
d.date();    // 15（日）
d.day();     // 1（曜日: 0=日, 1=月）
d.hour();    // 14
d.minute();  // 30
d.second();  // 0

// 設定（新しいDayjsオブジェクトを返す）
d.set('year', 2025).format('YYYY-MM-DD');  // "2025-07-15"
d.set('month', 0).format('YYYY-MM-DD');    // "2024-01-15"（0=1月）

// Unixタイムスタンプ
d.unix();       // 秒単位のタイムスタンプ
d.valueOf();    // ミリ秒単位のタイムスタンプ

プラグインで拡張する

Day.js はコアを小さく保ち、追加機能はプラグインで提供しています。よく使うプラグインの例を紹介します。

import dayjs from 'dayjs';
import relativeTime from 'dayjs/plugin/relativeTime';
import isBetween from 'dayjs/plugin/isBetween';
import duration from 'dayjs/plugin/duration';
import 'dayjs/locale/ja';

// プラグインの登録
dayjs.extend(relativeTime);
dayjs.extend(isBetween);
dayjs.extend(duration);

// ロケールを日本語に設定
dayjs.locale('ja');

// relativeTime — 相対時間の表示
dayjs('2024-01-01').fromNow();        // "6ヶ月前"
dayjs().add(3, 'day').fromNow();      // "3日後"
dayjs('2024-01-01').to(dayjs('2024-06-01')); // "5ヶ月後"

// isBetween — 範囲内判定
const target = dayjs('2024-03-15');
target.isBetween('2024-01-01', '2024-06-30'); // true

// duration — 期間の計算
const dur = dayjs.duration(90, 'minutes');
dur.hours();   // 1
dur.minutes(); // 30

ロケール（国際化）の使い方

import dayjs from 'dayjs';
import 'dayjs/locale/ja';

// グローバルに設定
dayjs.locale('ja');
dayjs('2024-07-15').format('ddd');  // "月"
dayjs('2024-07-15').format('dddd'); // "月曜日"

// 特定のインスタンスだけに適用
import 'dayjs/locale/en';
dayjs('2024-07-15').locale('en').format('dddd'); // "Monday"

類似パッケージとの比較

選定の目安:

• Moment.js からの移行 → dayjs（APIがほぼ同じで移行コスト最小）
• 関数型スタイルが好み / Tree-shaking を最大限活用したい → date-fns
• タイムゾーン操作が多い → Luxon

注意点・Tips

⚠️ month() は 0 始まり

Moment.js と同様に、月は 0始まり（0=1月, 11=12月）です。これは最も多いハマりポイントです。

dayjs('2024-03-15').month(); // 2（3月なのに2）
dayjs().set('month', 0);     // 1月

⚠️ プラグインを忘れると undefined やエラーになる

fromNow() や isBetween() などはプラグインを extend しないと使えません。エラーメッセージがわかりにくいので注意してください。

// ❌ プラグイン未登録だとエラー
dayjs().fromNow(); // TypeError: dayjs(...).fromNow is not a function

// ✅ 正しい使い方
import relativeTime from 'dayjs/plugin/relativeTime';
dayjs.extend(relativeTime);
dayjs().fromNow(); // "数秒前"

⚠️ タイムゾーンの扱い

デフォルトではローカルタイムゾーンで動作します。UTC やタイムゾーン変換が必要な場合はプラグインを使います。

import dayjs from 'dayjs';
import utc from 'dayjs/plugin/utc';
import timezone from 'dayjs/plugin/timezone';

dayjs.extend(utc);
dayjs.extend(timezone);

dayjs().tz('America/New_York').format('YYYY-MM-DD HH:mm');
dayjs.utc('2024-01-15T00:00:00Z').format();

💡 パース時はフォーマット指定を推奨

曖昧な文字列のパースはブラウザ依存の挙動になることがあります。customParseFormat プラグインで明示的にフォーマットを指定しましょう。

import customParseFormat from 'dayjs/plugin/customParseFormat';
dayjs.extend(customParseFormat);

// フォーマットを明示
dayjs('15/01/2024', 'DD/MM/YYYY').format('YYYY-MM-DD');
// => "2024-01-15"

💡 TypeScript でプラグインの型を効かせる

プラグインを import するだけで型定義が自動的にマージされます。特別な設定は不要ですが、tsconfig.json の moduleResolution が node または bundler であることを確認してください。

まとめ

dayjs は、Moment.js のAPIに慣れた開発者がほぼ学習コストゼロで移行できる、2KBの軽量日付ライブラリです。イミュータブル設計とプラグインによる拡張性を備え、バンドルサイズを最小限に抑えながら必要な機能だけを取り込めます。新規プロジェクトでも、Moment.js からの移行先としても、最初に検討すべき選択肢の一つです。