@tuqulore-inc/create-eleventy 5.2.2 → 5.3.1-alpha.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tuqulore-inc/create-eleventy",
3
- "version": "5.2.2",
3
+ "version": "5.3.1-alpha.0",
4
4
  "description": "Create a new Eleventy project with Preact and TailwindCSS",
5
5
  "keywords": [
6
6
  "create",
@@ -31,11 +31,11 @@
31
31
  "test": "node --test"
32
32
  },
33
33
  "devDependencies": {
34
- "@tuqulore-inc/oxlint-config": "5.2.2",
34
+ "@tuqulore-inc/oxlint-config": "5.3.1-alpha.0",
35
35
  "oxlint": "^1.88.0"
36
36
  },
37
37
  "engines": {
38
38
  "node": ">=20"
39
39
  },
40
- "gitHead": "b42fe67c4fc179fb17da4a046daf07c588e73f9d"
40
+ "gitHead": "0235813479c57041387d1c450dd44c3bce330244"
41
41
  }
@@ -18,13 +18,13 @@ pnpm dev # start the dev server
18
18
 
19
19
  ## npm scripts
20
20
 
21
- | Task | Description |
22
- | :----- | :------------------------ |
23
- | build | Generate the static site. |
24
- | clean | Remove build artifacts. |
25
- | dev | Start the dev server. |
26
- | format | Format code. |
27
- | lint | Run static checks. |
21
+ | Task | Description |
22
+ | :----- | :------------------------------------------ |
23
+ | build | Generate the static site. |
24
+ | clean | Remove build artifacts. |
25
+ | dev | Start the dev server. |
26
+ | format | Format code. |
27
+ | lint | Run static checks, including type checking. |
28
28
 
29
29
  ## Environment variables
30
30
 
@@ -121,6 +121,7 @@ Pass a component marked with `clientComponent()` to `<Island>`, and the same pro
121
121
  import { clientComponent } from "@tuqulore-inc/eleventy-preset/island";
122
122
  import { useSignal } from "@preact/signals";
123
123
 
124
+ /** @param {{ initial?: number }} props */
124
125
  function Counter(props) {
125
126
  const n = useSignal(props.initial ?? 0);
126
127
  return <button onClick={() => n.value++}>{n}</button>;
@@ -151,6 +152,73 @@ The `on` prop maps to the `<is-land>` initialization trigger (`interaction` / `v
151
152
  >
152
153
  > The [`<is-land>`](https://github.com/11ty/is-land?tab=readme-ov-file#usage) initialization attribute normally uses the `on:*` form, but that conflicts with JSX syntax, so this preset uses `land-on:*` instead. For parameterized triggers such as `on:media("(min-width: ...)")`, drop `<Island>` and use the raw `<is-land>` element.
153
154
 
155
+ ### Client-only islands
156
+
157
+ A component whose output differs between SSR and the browser (the current time, random values, `localStorage`), or that needs browser-only APIs to render, can skip SSR. Mark it with `clientOnlyComponent()` instead of `clientComponent()`. `<Island>` then emits only the `fallback` prop from SSR, and the client renders the component from scratch once the `on` trigger fires. When `on` is omitted, a client-only island renders on page load instead of waiting for an interaction, since its placeholder may have nothing to click.
158
+
159
+ ```jsx
160
+ // src/clock.client.jsx
161
+ import { clientOnlyComponent } from "@tuqulore-inc/eleventy-preset/island";
162
+
163
+ function Clock() {
164
+ return <time>{new Date().toLocaleTimeString()}</time>;
165
+ }
166
+
167
+ export default clientOnlyComponent(Clock, import.meta.url);
168
+ ```
169
+
170
+ ```mdx
171
+ <Island component={Clock} on="visible" fallback={<span>--:--:--</span>} />
172
+ ```
173
+
174
+ ```html
175
+ <is-land land-on:visible type="preact" import="/clock.client.js" props="[{}]" client-only>
176
+ <span>--:--:--</span>
177
+ </is-land>
178
+ ```
179
+
180
+ Size the `fallback` like the rendered component to avoid layout shift. See `src/clock.client.jsx` for a working example.
181
+
182
+ ## Types
183
+
184
+ `tsconfig.json` enables strict type checking, including for `.js` / `.jsx` files (`checkJs`), and `pnpm lint` runs it through oxlint (`--type-aware --type-check`). Annotate JavaScript with [JSDoc](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html), or rename a file to `.ts` / `.tsx` to write TypeScript.
185
+
186
+ ### Eleventy data
187
+
188
+ The `eleventy` singleton is typed. Built-in fields such as `eleventy.page` are typed out of the box; project-specific data is declared in `eleventy.env.d.ts` through declaration merging. `site` and `nav` are derived from the files under `src/_data/`, so they follow edits to those files. When you add a global data file or read a new front matter field, declare it in `eleventy.env.d.ts` as well.
189
+
190
+ > [!IMPORTANT]
191
+ >
192
+ > Keep at least one top-level `import` in `eleventy.env.d.ts`. Without one the file is not a module, and `declare module` replaces the package's types instead of extending them.
193
+
194
+ ### Collections
195
+
196
+ A directory under `src/` with a `_schema.ts` becomes a collection named after the directory. The build fails when an entry does not match the [Zod](https://zod.dev/) schema, and `eleventy.collections.<name>` is typed from it.
197
+
198
+ ```sh
199
+ pnpm add -D zod
200
+ pnpm exec eleventy-collections create posts # src/posts/_schema.ts and a sample .md
201
+ pnpm exec eleventy-collections create authors --type data # one entry per .json file
202
+ ```
203
+
204
+ Front matter is read as `post.data.title`. The types are written to `collections.d.ts` (git-ignored) by `pnpm build`, `pnpm dev`, and `pnpm lint`. See [@tuqulore-inc/eleventy-collections](https://github.com/tuqulore/website-boilerplate/tree/main/packages/eleventy-collections) for details.
205
+
206
+ ### Island props
207
+
208
+ `<Island>` checks its props against the props type of the wrapped client component. A misspelled or missing prop is a type error.
209
+
210
+ ### MDX
211
+
212
+ Install the recommended [MDX extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for VS Code to get the same type checking inside `.mdx` files (`"mdx": { "checkMdx": true }` in `tsconfig.json`). `pnpm lint` does not check `.mdx` files.
213
+
214
+ ### Loosening the checks
215
+
216
+ Narrow what gets checked instead of turning off `strict`. Without `strict`, `null` and `undefined` drop out of the types, so type-aware lint rules can misjudge nullable values, and `pnpm lint` applies their fixes automatically.
217
+
218
+ 1. Skip a single file: add `// @ts-nocheck` at the top.
219
+ 2. Skip JavaScript: set `"checkJs": false` in `tsconfig.json`. `.ts` / `.tsx` files are still checked.
220
+ 3. Skip type checking: remove `--type-aware --type-check` from the `lint` script.
221
+
154
222
  ## Docker
155
223
 
156
224
  To build and run a Docker image that serves the static site:
@@ -1,3 +1,4 @@
1
1
  .env*.local
2
+ /collections.d.ts
2
3
  dist
3
4
  node_modules
@@ -1,5 +1,6 @@
1
1
  {
2
2
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
3
3
  "sortImports": true,
4
- "sortTailwindcss": true
4
+ "sortTailwindcss": true,
5
+ "ignorePatterns": ["collections.d.ts"]
5
6
  }
@@ -24,5 +24,11 @@
24
24
  "env": { "commonjs": true }
25
25
  }
26
26
  ],
27
- "ignorePatterns": ["**/dist/**", "**/node_modules/**", "pnpm-lock.yaml", "**/*.mdx"]
27
+ "ignorePatterns": [
28
+ "**/dist/**",
29
+ "collections.d.ts",
30
+ "**/node_modules/**",
31
+ "pnpm-lock.yaml",
32
+ "**/*.mdx"
33
+ ]
28
34
  }
@@ -1,3 +1,3 @@
1
1
  {
2
- "recommendations": ["oxc.oxc-vscode"]
2
+ "recommendations": ["oxc.oxc-vscode", "unifiedjs.vscode-mdx"]
3
3
  }
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Types for project-specific Eleventy data, merged into the `eleventy`
3
+ * singleton. `site` and `nav` follow the `_data/` files; declare the front
4
+ * matter fields your templates read as well.
5
+ *
6
+ * NOTE: The top-level imports keep this file a module. Without them,
7
+ * `declare module` replaces the package's types instead of extending them.
8
+ */
9
+ import type nav from "./src/_data/nav.json";
10
+ import type site from "./src/_data/site.js";
11
+
12
+ declare module "@tuqulore-inc/eleventy-preset/eleventy" {
13
+ interface EleventyUserData {
14
+ site: typeof site;
15
+ nav: typeof nav;
16
+ /** Front matter: OGP image path. */
17
+ ogp?: string;
18
+ }
19
+ }
@@ -8,7 +8,7 @@
8
8
  "clean": "shx rm -rf dist",
9
9
  "dev": "dotenv -c development -- eleventy --serve",
10
10
  "format": "oxfmt",
11
- "lint": "oxlint --fix"
11
+ "lint": "eleventy-collections sync && oxlint --fix --type-aware --type-check"
12
12
  },
13
13
  "dependencies": {
14
14
  "serve-handler": "^6.1.6"
@@ -21,12 +21,17 @@
21
21
  "@preact/signals": "^2.9.3",
22
22
  "@tailwindcss/postcss": "^4.0.14",
23
23
  "@tailwindcss/typography": "0.5.20",
24
- "@tuqulore-inc/eleventy-preset": "^5.2.2",
24
+ "@tuqulore-inc/eleventy-collections": "^5.3.0",
25
+ "@tuqulore-inc/eleventy-preset": "^5.3.0",
26
+ "@types/node": "^24.19.2",
27
+ "@types/serve-handler": "^6.1.4",
25
28
  "dotenv-cli": "^11.0.0",
26
29
  "npm-run-all2": "^9.0.0",
27
30
  "oxfmt": "^0.65.0",
28
31
  "oxlint": "^1.88.0",
32
+ "oxlint-tsgolint": "^7.0.2004",
29
33
  "postcss": "^8.5.6",
34
+ "postcss-load-config": "^6.0.1",
30
35
  "preact": "^10.26.4",
31
36
  "shx": "^0.4.0",
32
37
  "tailwind-merge": "^3.0.2",
@@ -25,7 +25,7 @@ import Footer from "./partials/footer.mdx";
25
25
  <main
26
26
  id="main"
27
27
  class="mx-auto mb-4 min-h-[60vh] max-w-6xl px-4"
28
- dangerouslySetInnerHTML={{ __html: eleventy.content }}
28
+ dangerouslySetInnerHTML={{ __html: eleventy.content ?? "" }}
29
29
  ></main>
30
30
  <Footer />
31
31
  </body>
@@ -3,6 +3,10 @@ import { clientComponent } from "@tuqulore-inc/eleventy-preset/island";
3
3
  import { useId, useRef } from "preact/hooks";
4
4
  import { twMerge } from "tailwind-merge";
5
5
 
6
+ /** @import { ComponentChildren, RefObject } from "preact" */
7
+ /** @import { EleventyData } from "@tuqulore-inc/eleventy-preset/eleventy" */
8
+
9
+ /** @param {{ item: { name: string }; children: ComponentChildren }} props */
6
10
  function MenuList(props) {
7
11
  const open = useSignal(false);
8
12
  const visible = useSignal(open.value);
@@ -12,18 +16,22 @@ function MenuList(props) {
12
16
  const handleTransitionEnd = () => {
13
17
  if (!open.value) visible.value = false;
14
18
  };
19
+ /** @type {RefObject<HTMLDivElement>} */
15
20
  const ref = useRef(null);
21
+ /** @type {RefObject<HTMLButtonElement>} */
16
22
  const buttonRef = useRef(null);
17
23
  const baseId = useId();
18
24
  useSignalEffect(() => {
19
- if (!open.value) return;
25
+ if (!open.value) return undefined;
26
+ /** @param {MouseEvent} e */
20
27
  const clickHandler = (e) => {
21
- if (ref.current?.contains(e.target)) return;
28
+ if (e.target instanceof Node && ref.current?.contains(e.target)) return;
22
29
  open.value = false;
23
30
  };
31
+ /** @param {KeyboardEvent} e */
24
32
  const keyHandler = (e) => {
25
33
  if (e.key !== "Escape") return;
26
- if (!ref.current?.contains(e.target)) return;
34
+ if (!(e.target instanceof Node) || !ref.current?.contains(e.target)) return;
27
35
  open.value = false;
28
36
  buttonRef.current?.focus();
29
37
  };
@@ -38,7 +46,7 @@ function MenuList(props) {
38
46
  <div
39
47
  ref={ref}
40
48
  onFocusOut={(e) => {
41
- if (ref.current?.contains(e.relatedTarget)) return;
49
+ if (e.relatedTarget instanceof Node && ref.current?.contains(e.relatedTarget)) return;
42
50
  open.value = false;
43
51
  }}
44
52
  >
@@ -71,12 +79,13 @@ function MenuList(props) {
71
79
  );
72
80
  }
73
81
 
82
+ /** @param {{ nav: EleventyData["nav"]; class?: string }} props */
74
83
  function Desktop(props) {
75
84
  return (
76
85
  <nav class={props.class}>
77
86
  <ul class="flex items-center">
78
87
  {props.nav.map((item) =>
79
- "children" in item ? (
88
+ item.children ? (
80
89
  <li key={item.name} class="relative">
81
90
  <MenuList item={item}>
82
91
  {item.children.map((child) => (
@@ -3,15 +3,19 @@ import { clientComponent } from "@tuqulore-inc/eleventy-preset/island";
3
3
  import { useId, useRef } from "preact/hooks";
4
4
  import { twMerge } from "tailwind-merge";
5
5
 
6
+ /** @import { RefObject } from "preact" */
7
+ /** @import { EleventyData } from "@tuqulore-inc/eleventy-preset/eleventy" */
8
+
9
+ /** @param {{ name: string; items: readonly { name: string; path: string }[] }} props */
6
10
  function NavGroup(props) {
7
11
  const groupId = useId();
8
12
  return (
9
13
  <div class="mb-6">
10
14
  <p id={groupId} class="mb-2 ml-4 text-lg">
11
- {props.item.name}
15
+ {props.name}
12
16
  </p>
13
17
  <ul aria-labelledby={groupId}>
14
- {props.item.children.map((child) => (
18
+ {props.items.map((child) => (
15
19
  <li key={child.name}>
16
20
  <a class="jumpu-text-button block" href={child.path}>
17
21
  {child.name}
@@ -23,16 +27,20 @@ function NavGroup(props) {
23
27
  );
24
28
  }
25
29
 
30
+ /** @param {{ nav: EleventyData["nav"]; class?: string }} props */
26
31
  function Mobile(props) {
27
32
  const open = useSignal(false);
33
+ /** @type {RefObject<HTMLButtonElement>} */
28
34
  const openButtonRef = useRef(null);
35
+ /** @type {RefObject<HTMLButtonElement>} */
29
36
  const closeButtonRef = useRef(null);
30
37
  useSignalEffect(() => {
31
- if (!open.value) return;
38
+ if (!open.value) return undefined;
32
39
  closeButtonRef.current?.focus();
33
40
  // NOTE: メニュー表示中は背景 (html) のスクロールを止め、モバイルで
34
41
  // メニューをスクロールしたつもりが背後のページも動く事故を防ぐ。
35
42
  document.documentElement.classList.add("overflow-hidden");
43
+ /** @param {KeyboardEvent} e */
36
44
  const handler = (e) => {
37
45
  if (e.key !== "Escape") return;
38
46
  open.value = false;
@@ -83,7 +91,7 @@ function Mobile(props) {
83
91
  <ul class="flex flex-col px-4 py-16">
84
92
  {props.nav.map((item) => (
85
93
  <li key={item.name}>
86
- {item.children && <NavGroup item={item} />}
94
+ {item.children && <NavGroup name={item.name} items={item.children} />}
87
95
  {item.path && (
88
96
  <a class="jumpu-text-button block" href={item.path}>
89
97
  {item.name}
@@ -4,4 +4,4 @@ layout: base
4
4
 
5
5
  import { eleventy } from "@tuqulore-inc/eleventy-preset/eleventy";
6
6
 
7
- <article class="prose" dangerouslySetInnerHTML={{ __html: eleventy.content }} />
7
+ <article class="prose" dangerouslySetInnerHTML={{ __html: eleventy.content ?? "" }} />
@@ -0,0 +1,20 @@
1
+ import { clientOnlyComponent } from "@tuqulore-inc/eleventy-preset/island";
2
+ import { useEffect, useState } from "preact/hooks";
3
+
4
+ /** @param {{ locale: string }} props */
5
+ function Clock(props) {
6
+ const [now, setNow] = useState(() => new Date());
7
+
8
+ useEffect(() => {
9
+ const timer = setInterval(() => setNow(new Date()), 1000);
10
+ return () => clearInterval(timer);
11
+ }, []);
12
+
13
+ return (
14
+ <time class="text-xl tabular-nums" dateTime={now.toISOString()}>
15
+ {now.toLocaleTimeString(props.locale)}
16
+ </time>
17
+ );
18
+ }
19
+
20
+ export default clientOnlyComponent(Clock, import.meta.url);
@@ -5,6 +5,7 @@ title: ようこそ
5
5
 
6
6
  import { Island } from "@tuqulore-inc/eleventy-preset/island";
7
7
  import Clicker from "./clicker.client.jsx";
8
+ import Clock from "./clock.client.jsx";
8
9
 
9
10
  # ようこそ
10
11
 
@@ -22,3 +23,14 @@ import Clicker from "./clicker.client.jsx";
22
23
  以下のカウンターは Preact コンポーネントで、表示領域に入ったタイミングでクライアント側でハイドレーションされます。
23
24
 
24
25
  <Island component={Clicker} on="visible" />
26
+
27
+ ## SSR しない Island のサンプル
28
+
29
+ 以下の時計は `clientOnlyComponent()` で宣言した Preact コンポーネントです。現在時刻は SSR とクライアントで値が食い違うため、SSR ではプレースホルダだけを出力し、表示領域に入ったタイミングでクライアント側で初めて描画します。
30
+
31
+ <Island
32
+ component={Clock}
33
+ on="visible"
34
+ locale="ja-JP"
35
+ fallback={<span class="text-xl tabular-nums">--:--:--</span>}
36
+ />
@@ -0,0 +1,25 @@
1
+ {
2
+ "compilerOptions": {
3
+ "noEmit": true,
4
+ "allowImportingTsExtensions": true,
5
+ "allowJs": true,
6
+ "checkJs": true,
7
+ "resolveJsonModule": true,
8
+ "target": "ES2022",
9
+ "module": "ESNext",
10
+ "moduleResolution": "Bundler",
11
+ "esModuleInterop": true,
12
+ "verbatimModuleSyntax": true,
13
+ "types": ["node"],
14
+ "jsx": "react-jsx",
15
+ "jsxImportSource": "preact",
16
+ "strict": true,
17
+ "skipLibCheck": true,
18
+ "noUncheckedIndexedAccess": true
19
+ },
20
+ "mdx": {
21
+ "checkMdx": true
22
+ },
23
+ "include": ["*.js", "*.d.ts", "src/**/*"],
24
+ "exclude": ["dist", "node_modules"]
25
+ }