note-blog-kit 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -19,7 +19,7 @@
19
19
  npm install note-blog-kit
20
20
  ```
21
21
 
22
- React のコンポーネント(`note-blog-kit/react`)を使う場合は React 18 / 19 が必要です。取得(`note-blog-kit/server`)は Node.js 20 以上で動きます。
22
+ React のコンポーネント(`note-blog-kit/react`)を使う場合は React 18 / 19 が必要です。取得(`note-blog-kit/server`)は Node.js 22.12 以上で動きます。
23
23
 
24
24
  ### 2. デフォルト CSS を読み込む(任意)
25
25
 
@@ -62,7 +62,55 @@ export default async function BlogPage({ searchParams }: Props) {
62
62
  }
63
63
  ```
64
64
 
65
- 記事のリンク先は、既定では note の記事ページです。自分のサイトの詳細ページにしたい場合は `getHref` と `linkComponent={Link}` を渡します(詳細ページの作り方は今後のリリースで追加します)。
65
+ 記事のリンク先は、既定では note の記事ページです。自分のサイトの詳細ページにしたい場合は `getHref` と `linkComponent={Link}` を渡します(下の「4. 詳細ページを作る」)。
66
+
67
+ ### 4. 詳細ページを作る(任意)
68
+
69
+ `app/articles/[key]/page.tsx` を作ります。`note-blog-kit/next` のヘルパーで、静的生成するキーと metadata を作れます。
70
+
71
+ ```tsx
72
+ import { generateNoteMetadata, generateNoteStaticParams } from 'note-blog-kit/next';
73
+ import { NoteArticleBody } from 'note-blog-kit/react';
74
+ import { getArticle, isNoteError } from 'note-blog-kit/server';
75
+ import { notFound } from 'next/navigation';
76
+
77
+ const USER = 'your_urlname';
78
+ type Props = { params: Promise<{ key: string }> };
79
+
80
+ async function findArticle(key: string) {
81
+ const article = await getArticle({ key }).catch((error: unknown) => {
82
+ // 不正なキー・見つからない記事だけ 404 にする(タイムアウトなどは 404 にしない)
83
+ if (error instanceof TypeError || (isNoteError(error) && error.code === 'NOTE_NOT_FOUND')) return null;
84
+ throw error;
85
+ });
86
+ // getArticle は誰の記事でも返すので、自分の記事か確かめる
87
+ if (article === null || article.author.urlname !== USER) notFound();
88
+ return article;
89
+ }
90
+
91
+ // ビルド時に新しい記事から 20 ページ分(120件)を生成する(maxPages で変更できる)
92
+ export const generateStaticParams = () => generateNoteStaticParams({ user: USER });
93
+
94
+ export async function generateMetadata({ params }: Props) {
95
+ // canonical は既定で note の元 URL。自分のサイトを正にするなら { canonical: '...' } を渡す
96
+ return generateNoteMetadata(await findArticle((await params).key));
97
+ }
98
+
99
+ export default async function ArticlePage({ params }: Props) {
100
+ const article = await findArticle((await params).key);
101
+ return (
102
+ <main>
103
+ <h1>{article.title}</h1>
104
+ <NoteArticleBody article={article} />
105
+ </main>
106
+ );
107
+ }
108
+ ```
109
+
110
+ - **キャッシュ**:`generateMetadata` とページで同じ記事を取得するので、`unstable_cache` などで結果をキャッシュしてください([`examples/next`](https://github.com/ludy-kida/note-blog-kit/tree/main/examples/next) の詳細ページを参照)
111
+ - **URL のキーは外部から自由に指定されます**:上の例のままだと、形式が正しいキーなら自分の記事でなくても note に問い合わせます。公開するサイトでは、自分の記事のキーの一覧(`generateNoteStaticParams` の結果をキャッシュしたもの)にあるときだけ `getArticle` を呼んでください(`examples/next` はそうしています)
112
+ - **`generateNoteStaticParams`**:`listAllArticles` で記事を集めます。`maxPages`(既定 20 ページ)を超える古い記事はビルド時には生成しませんが、`dynamicParams` を既定の true のままにしておけば最初のアクセス時に表示できます。`param` で動的セグメントの名前(既定 `'key'`)を変えられます
113
+ - **`generateNoteMetadata`**:`title`・`description`(抜粋)・`alternates.canonical`・Open Graph・Twitter カードを返します。Next.js の `Metadata` にそのまま代入できます(`note-blog-kit` は `next` に依存しません)。`formatTitle` でタイトルを加工できます
66
114
 
67
115
  ### キャッシュの推奨
68
116
 
@@ -130,6 +178,26 @@ for await (const article of iterateArticles({ user: 'your_urlname' })) {
130
178
  - `listAllArticles` は途中のページで失敗すると、それまでに集めた記事を返さずにエラーを投げます。途中までの記事も使いたい場合は `iterateArticles` を使ってください
131
179
  - `for await` では打ち切りの有無を受け取れません。必要なら `listAllArticles` を使うか、`next()` を手で回して戻り値(`done: true` のときの `value`)を読んでください
132
180
 
181
+ ### 記事1件を取得する(サーバー側)
182
+
183
+ ```ts
184
+ import { getArticle } from 'note-blog-kit/server';
185
+
186
+ const article = await getArticle({ key: 'n55256baa5425' }); // 記事 URL の /n/ の後ろ
187
+
188
+ // note の API は記事キーだけで誰の記事でも返します。他人の記事を表示しないよう、著者を確かめてください
189
+ if (article.author.urlname !== 'your_urlname') {
190
+ // 404 として扱う
191
+ }
192
+
193
+ article.bodyHtml; // サニタイズ済みの本文 HTML(サニタイズは外せません)
194
+ article.isPartial; // 有料記事で本文が途中までのとき true(「続きは note で」を出す)
195
+ article.toc; // 目次(id は本文の見出しの id と同じ。有料記事では有料部分の見出しも含む)
196
+ article.embeds; // 本文中の埋め込み(本文の <figure data-nbk-embed-key> と key で対応)
197
+ ```
198
+
199
+ `key` は `n` と英小文字・数字だけを受け付け、それ以外は送信せずに `TypeError` を投げます(ページの URL から受け取った値なら 404 として扱ってください)。オプション(`fetch`・`signal`・`timeoutMs`・`minIntervalMs`)とエラーは `listArticles` と同じです。結果は必ずキャッシュしてください。
200
+
133
201
  ### 一覧を表示する(React)
134
202
 
135
203
  `note-blog-kit/react` のコンポーネントは、取得済みのデータを受け取って描画するだけです。見た目は持たず、`nbk-` から始まるクラス名を付けます。フックを使わないため、Server Component としても使えます(React 18 / 19)。
@@ -161,6 +229,48 @@ export default async function BlogPage() {
161
229
  - **Next.js の typedRoutes**:有効にしている場合は `Link` の `href` が文字列を受け付けないため、`Link` を包んだコンポーネントを `linkComponent` に渡してください
162
230
  - **見出し画像**:note の CDN(assets.st-note.com)から直接読み込みます
163
231
 
232
+ ### 本文を表示する(React)
233
+
234
+ `NoteArticleBody` は `getArticle` で取得した記事の本文を描画します。`dangerouslySetInnerHTML` は使わず、サニタイズ済みの本文を、許可したタグ・属性だけの React 要素にします。有料記事(`isPartial`)では、本文の後に「続きは note で」リンクを出します。
235
+
236
+ ```tsx
237
+ import { getArticle } from 'note-blog-kit/server';
238
+ import { NoteArticleBody } from 'note-blog-kit/react';
239
+
240
+ export default async function Page({ params }: { params: Promise<{ key: string }> }) {
241
+ const article = await getArticle({ key: (await params).key });
242
+ return (
243
+ <article>
244
+ <h1>{article.title}</h1>
245
+ <NoteArticleBody
246
+ article={article}
247
+ components={{
248
+ // 画像・見出し・埋め込み・目次を任意のコンポーネントに置き換えられる
249
+ img: ({ src, alt, width, height }) => <img src={src} alt={alt} width={width} height={height} />,
250
+ }}
251
+ labels={{ readMore: '続きを note で読む' }}
252
+ />
253
+ </article>
254
+ );
255
+ }
256
+ ```
257
+
258
+ | props | 内容 |
259
+ | --- | --- |
260
+ | `article`(必須) | `getArticle` の戻り値 |
261
+ | `components` | `img`(`src`・`alt`・`width`・`height`)、`heading`(`level`: 2〜4・`id`・`children`)、`embed`(`embed`: `NoteEmbed \| null`・`service`・`children`)、`toc`(`items`)を置き換える |
262
+ | `readMoreHref` | 「続きは note で」のリンク先。既定は記事 URL(http(s) でなければ出さない) |
263
+ | `linkComponent` | 「続きは note で」と note の埋め込みのリンクに使う要素。既定は `'a'` |
264
+ | `labels` | `readMore`(既定「続きは note で」)、`toc`(既定「目次」) |
265
+
266
+ - **既定の描画**:外部記事の埋め込みは中のリンクカード、note の埋め込みは記事へのリンクを出します(`iframe` は出しません)。目次の位置には `article.toc` を出し、本文にない見出し(有料部分)はリンクにしません
267
+ - **クラス名**:
268
+ - `nbk-body`(`__more`・`__more-link`)
269
+ - 本文の要素:`nbk-body__p`・`__h2`・`__h3`・`__h4`・`__a`・`__ul`・`__ol`・`__blockquote`・`__figure`・`__figcaption`・`__img`・`__pre`・`__code`・`__hr`・`__table`・`__th`・`__td`。`li`・`strong`・`em` などにはクラスを付けません。`components` で置き換えた画像・見出しにも付きません
270
+ - `nbk-toc`(`__title`・`__list`・`__item`・`__item--h2`/`--h3`・`__link`)
271
+ - `nbk-embed`(`data-service` 属性)。埋め込みの中のリンクは `nbk-body__a` ではなく `nbk-embed__link` になります
272
+ - **他人の記事**:`getArticle` は誰の記事でも返します。URL から受け取ったキーで表示する場合は、`article.author.urlname` を確かめてください
273
+
164
274
  ### デフォルト CSS(任意)
165
275
 
166
276
  note の見た目に合わせた CSS を用意しています。読み込まなければ、コンポーネントは見た目を持ちません。
@@ -185,6 +295,11 @@ CSS は `:root`(変数の既定値)と `nbk-` から始まるクラスにだ
185
295
  | `--nbk-radius` | `8px` | 角丸 |
186
296
  | `--nbk-list-gap` | `24px` | 一覧のカードの間隔、ページ送りの上下の余白 |
187
297
  | `--nbk-card-min-width` | `280px` | 一覧で1枚のカードが取る最小幅 |
298
+ | `--nbk-body-max-width` | `620px` | 本文の最大幅 |
299
+ | `--nbk-body-font-size` / `--nbk-body-line-height` | `18px` / `2` | 本文の文字サイズ・行間(note に合わせた値) |
300
+ | `--nbk-body-gap` | `1.5em` | 本文の段落などの間隔 |
301
+ | `--nbk-color-subtle` | `#f5f8fa` | コードブロック・目次の背景 |
302
+ | `--nbk-color-button-bg` / `--nbk-color-button-text` | `#08131a` / `#fff` | 「続きは note で」ボタン |
188
303
 
189
304
  #### 優先順位(カスケードレイヤー)
190
305
 
package/dist/index.d.cts CHANGED
@@ -21,7 +21,7 @@ interface NoteArticleSummary {
21
21
  url: string;
22
22
  /** ISO 8601 */
23
23
  publishedAt: string;
24
- /** 本文先頭のプレーンテキスト */
24
+ /** 本文先頭のプレーンテキスト。`<` などがそのまま入りうるので、HTML として挿入しないこと */
25
25
  excerpt: string;
26
26
  eyecatchUrl: string | null;
27
27
  /** 先頭の # を除いたハッシュタグ。RSS では常に空 */
@@ -44,6 +44,7 @@ interface NoteEyecatch {
44
44
  interface NoteTocItem {
45
45
  /** 本文中の見出しの id */
46
46
  id: string;
47
+ /** 見出しのプレーンテキスト。HTML として挿入しないこと */
47
48
  text: string;
48
49
  level: 2 | 3;
49
50
  }
package/dist/index.d.ts CHANGED
@@ -21,7 +21,7 @@ interface NoteArticleSummary {
21
21
  url: string;
22
22
  /** ISO 8601 */
23
23
  publishedAt: string;
24
- /** 本文先頭のプレーンテキスト */
24
+ /** 本文先頭のプレーンテキスト。`<` などがそのまま入りうるので、HTML として挿入しないこと */
25
25
  excerpt: string;
26
26
  eyecatchUrl: string | null;
27
27
  /** 先頭の # を除いたハッシュタグ。RSS では常に空 */
@@ -44,6 +44,7 @@ interface NoteEyecatch {
44
44
  interface NoteTocItem {
45
45
  /** 本文中の見出しの id */
46
46
  id: string;
47
+ /** 見出しのプレーンテキスト。HTML として挿入しないこと */
47
48
  text: string;
48
49
  level: 2 | 3;
49
50
  }
@@ -0,0 +1,84 @@
1
+ import { NoteArticlePage, NoteArticleSummary } from './index.js';
2
+
3
+ /** 取得関数に共通するオプションの型・既定値・検証 */
4
+ /** note から取得する関数(listArticles・getArticle など)に共通するオプション */
5
+ interface NoteRequestOptions {
6
+ /**
7
+ * fetch の差し替え(テストやキャッシュ層のため)。既定は globalThis.fetch。
8
+ * 差し替えた fetch でも Cookie・認証ヘッダーを付けないこと(note の公開情報だけを取得する前提)
9
+ */
10
+ fetch?: typeof globalThis.fetch;
11
+ /** 中断用のシグナル。間隔の制限で待っている間も含め、中断したらすぐにその理由をそのまま投げる */
12
+ signal?: AbortSignal;
13
+ /** タイムアウト(ミリ秒)。1〜2147483647。既定は 10000 */
14
+ timeoutMs?: number;
15
+ /**
16
+ * 連続リクエストの最小間隔(ミリ秒)。0〜2147483647。既定は 1000。
17
+ * 送信順はプロセス全体(ESM・CJS の併用やパッケージの重複を含む)で1本の列にまとめられ、
18
+ * この呼び出しは「直前の送信から minIntervalMs 経つまで」待ってから送られる。
19
+ */
20
+ minIntervalMs?: number;
21
+ }
22
+
23
+ /** `listArticles` のオプション(`note-blog-kit/next` からも参照するため @link は使わない) */
24
+ interface ListArticlesOptions extends NoteRequestOptions {
25
+ /** note のユーザー名(note.com/{user} の部分)。英数字・_・- のみ */
26
+ user: string;
27
+ /** ページ番号(1 始まり)。既定は 1。1ページは6件 */
28
+ page?: number;
29
+ }
30
+ /**
31
+ * 記事一覧の1ページを取得する(サーバー専用。note は CORS に対応していない)。
32
+ *
33
+ * @throws {TypeError} user・page が不正なとき
34
+ * @throws {NoteNotFoundError} ユーザーが見つからないとき
35
+ * @throws {NoteHttpError} その他の 2xx でないステータス
36
+ * @throws {NoteNetworkError} 通信に失敗したとき
37
+ * @throws {NoteTimeoutError} タイムアウトしたとき
38
+ * @throws {NoteSchemaError} レスポンスの形が想定と違うとき
39
+ */
40
+ declare function listArticles(options: ListArticlesOptions): Promise<NoteArticlePage>;
41
+
42
+ /** `iterateArticles`・`listAllArticles` のオプション(`note-blog-kit/next` からも参照するため @link は使わない)。`listArticles` のオプションから `page` を除いたもの */
43
+ interface IterateArticlesOptions extends Omit<ListArticlesOptions, 'page'> {
44
+ /** 取得する最大ページ数(1 以上の整数)。既定は 20(1ページ6件なので120件) */
45
+ maxPages?: number;
46
+ }
47
+ /** 全件取得の結果のうち、記事以外の情報 */
48
+ interface IterateArticlesResult {
49
+ /** maxPages に達して打ち切ったとき true(続きのページがある可能性がある) */
50
+ truncated: boolean;
51
+ /** 最後に取得したページの totalCount */
52
+ totalCount: number | null;
53
+ /** 実際に取得したページ数 */
54
+ pages: number;
55
+ }
56
+ /** {@link listAllArticles} の結果 */
57
+ interface ListAllArticlesResult extends IterateArticlesResult {
58
+ /** 取得した記事(新しい順、key で重複を除いたもの) */
59
+ articles: NoteArticleSummary[];
60
+ }
61
+ /**
62
+ * 記事を新しい順に1件ずつ返す(サーバー専用)。最終ページか maxPages に達したら終わる。
63
+ * ページの取得には `listArticles` を使うため、取得間隔の制限・タイムアウト・中断もそのまま効く。
64
+ * 取得中にページがずれて同じ記事が再び出た場合は、`key` で重複を除く。
65
+ *
66
+ * 打ち切りの有無などはジェネレーターの戻り値(`IterateArticlesResult`)で返す。
67
+ * `for await` ではこの戻り値を受け取れないため、必要なら {@link listAllArticles} を使うか `next()` を手で回す。
68
+ *
69
+ * @throws {TypeError} maxPages などが不正なとき(呼び出した時点ではなく、最初の `next()` で投げる)
70
+ * @throws 途中のページの取得で起きたエラー(それまでに返した記事はそのまま)
71
+ */
72
+ declare function iterateArticles(options: IterateArticlesOptions): AsyncGenerator<NoteArticleSummary, IterateArticlesResult, undefined>;
73
+ /**
74
+ * 全件(maxPages まで。既定は 20 ページ)を配列で返す(サーバー専用)。
75
+ * `truncated` が true なら maxPages で打ち切っており、続きのページがある可能性がある。
76
+ *
77
+ * @throws {TypeError} maxPages などが不正なとき
78
+ * @throws 途中のページの取得で起きたエラー。それまでに集めた記事は返らない
79
+ * (途中までの記事も使いたい場合は {@link iterateArticles} を使う)
80
+ */
81
+ declare function listAllArticles(options: IterateArticlesOptions): Promise<ListAllArticlesResult>;
82
+
83
+ export { listArticles as c, iterateArticles as i, listAllArticles as l };
84
+ export type { IterateArticlesOptions as I, ListArticlesOptions as L, NoteRequestOptions as N, IterateArticlesResult as a, ListAllArticlesResult as b };
@@ -0,0 +1,84 @@
1
+ import { NoteArticlePage, NoteArticleSummary } from './index.cjs';
2
+
3
+ /** 取得関数に共通するオプションの型・既定値・検証 */
4
+ /** note から取得する関数(listArticles・getArticle など)に共通するオプション */
5
+ interface NoteRequestOptions {
6
+ /**
7
+ * fetch の差し替え(テストやキャッシュ層のため)。既定は globalThis.fetch。
8
+ * 差し替えた fetch でも Cookie・認証ヘッダーを付けないこと(note の公開情報だけを取得する前提)
9
+ */
10
+ fetch?: typeof globalThis.fetch;
11
+ /** 中断用のシグナル。間隔の制限で待っている間も含め、中断したらすぐにその理由をそのまま投げる */
12
+ signal?: AbortSignal;
13
+ /** タイムアウト(ミリ秒)。1〜2147483647。既定は 10000 */
14
+ timeoutMs?: number;
15
+ /**
16
+ * 連続リクエストの最小間隔(ミリ秒)。0〜2147483647。既定は 1000。
17
+ * 送信順はプロセス全体(ESM・CJS の併用やパッケージの重複を含む)で1本の列にまとめられ、
18
+ * この呼び出しは「直前の送信から minIntervalMs 経つまで」待ってから送られる。
19
+ */
20
+ minIntervalMs?: number;
21
+ }
22
+
23
+ /** `listArticles` のオプション(`note-blog-kit/next` からも参照するため @link は使わない) */
24
+ interface ListArticlesOptions extends NoteRequestOptions {
25
+ /** note のユーザー名(note.com/{user} の部分)。英数字・_・- のみ */
26
+ user: string;
27
+ /** ページ番号(1 始まり)。既定は 1。1ページは6件 */
28
+ page?: number;
29
+ }
30
+ /**
31
+ * 記事一覧の1ページを取得する(サーバー専用。note は CORS に対応していない)。
32
+ *
33
+ * @throws {TypeError} user・page が不正なとき
34
+ * @throws {NoteNotFoundError} ユーザーが見つからないとき
35
+ * @throws {NoteHttpError} その他の 2xx でないステータス
36
+ * @throws {NoteNetworkError} 通信に失敗したとき
37
+ * @throws {NoteTimeoutError} タイムアウトしたとき
38
+ * @throws {NoteSchemaError} レスポンスの形が想定と違うとき
39
+ */
40
+ declare function listArticles(options: ListArticlesOptions): Promise<NoteArticlePage>;
41
+
42
+ /** `iterateArticles`・`listAllArticles` のオプション(`note-blog-kit/next` からも参照するため @link は使わない)。`listArticles` のオプションから `page` を除いたもの */
43
+ interface IterateArticlesOptions extends Omit<ListArticlesOptions, 'page'> {
44
+ /** 取得する最大ページ数(1 以上の整数)。既定は 20(1ページ6件なので120件) */
45
+ maxPages?: number;
46
+ }
47
+ /** 全件取得の結果のうち、記事以外の情報 */
48
+ interface IterateArticlesResult {
49
+ /** maxPages に達して打ち切ったとき true(続きのページがある可能性がある) */
50
+ truncated: boolean;
51
+ /** 最後に取得したページの totalCount */
52
+ totalCount: number | null;
53
+ /** 実際に取得したページ数 */
54
+ pages: number;
55
+ }
56
+ /** {@link listAllArticles} の結果 */
57
+ interface ListAllArticlesResult extends IterateArticlesResult {
58
+ /** 取得した記事(新しい順、key で重複を除いたもの) */
59
+ articles: NoteArticleSummary[];
60
+ }
61
+ /**
62
+ * 記事を新しい順に1件ずつ返す(サーバー専用)。最終ページか maxPages に達したら終わる。
63
+ * ページの取得には `listArticles` を使うため、取得間隔の制限・タイムアウト・中断もそのまま効く。
64
+ * 取得中にページがずれて同じ記事が再び出た場合は、`key` で重複を除く。
65
+ *
66
+ * 打ち切りの有無などはジェネレーターの戻り値(`IterateArticlesResult`)で返す。
67
+ * `for await` ではこの戻り値を受け取れないため、必要なら {@link listAllArticles} を使うか `next()` を手で回す。
68
+ *
69
+ * @throws {TypeError} maxPages などが不正なとき(呼び出した時点ではなく、最初の `next()` で投げる)
70
+ * @throws 途中のページの取得で起きたエラー(それまでに返した記事はそのまま)
71
+ */
72
+ declare function iterateArticles(options: IterateArticlesOptions): AsyncGenerator<NoteArticleSummary, IterateArticlesResult, undefined>;
73
+ /**
74
+ * 全件(maxPages まで。既定は 20 ページ)を配列で返す(サーバー専用)。
75
+ * `truncated` が true なら maxPages で打ち切っており、続きのページがある可能性がある。
76
+ *
77
+ * @throws {TypeError} maxPages などが不正なとき
78
+ * @throws 途中のページの取得で起きたエラー。それまでに集めた記事は返らない
79
+ * (途中までの記事も使いたい場合は {@link iterateArticles} を使う)
80
+ */
81
+ declare function listAllArticles(options: IterateArticlesOptions): Promise<ListAllArticlesResult>;
82
+
83
+ export { listArticles as c, iterateArticles as i, listAllArticles as l };
84
+ export type { IterateArticlesOptions as I, ListArticlesOptions as L, NoteRequestOptions as N, IterateArticlesResult as a, ListAllArticlesResult as b };