create-ampless 1.0.0-alpha.75 → 1.0.0-alpha.77
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/dist/index.js
CHANGED
|
@@ -1798,9 +1798,18 @@ var PROTECTED_PATTERNS = [
|
|
|
1798
1798
|
// Anything under themes/ is handled by syncThemes; the file-walk
|
|
1799
1799
|
// classifier must not double-process it.
|
|
1800
1800
|
/^themes(\/|$)/,
|
|
1801
|
-
/^themes-registry\.ts
|
|
1801
|
+
/^themes-registry\.ts$/,
|
|
1802
|
+
// `plugins/` is the site-local plugin directory (user-owned, mirrors
|
|
1803
|
+
// the `themes/my-*` convention for user-customised themes). The
|
|
1804
|
+
// initial scaffold seeds a README into this directory; everything
|
|
1805
|
+
// afterwards is the user's territory. We never overwrite or delete
|
|
1806
|
+
// files here — even the seeded README is frozen at scaffold time,
|
|
1807
|
+
// because plugin authors will sometimes edit it to document the
|
|
1808
|
+
// site's own conventions. The kept-up-to-date "how to write a
|
|
1809
|
+
// plugin" doc lives in `packages/ampless/docs/plugin-author-guide.md`.
|
|
1810
|
+
/^plugins(\/|$)/
|
|
1802
1811
|
];
|
|
1803
|
-
var SEED_IF_MISSING_PATTERN = /\.custom\.ts$/;
|
|
1812
|
+
var SEED_IF_MISSING_PATTERN = /\.custom\.ts$|^plugins\/README(\.ja)?\.md$/;
|
|
1804
1813
|
var TEXT_EXTENSIONS2 = /* @__PURE__ */ new Set([
|
|
1805
1814
|
".json",
|
|
1806
1815
|
".md",
|
|
@@ -1820,6 +1829,7 @@ var TEXT_EXTENSIONS2 = /* @__PURE__ */ new Set([
|
|
|
1820
1829
|
".gitignore"
|
|
1821
1830
|
]);
|
|
1822
1831
|
function isProtected(relPath) {
|
|
1832
|
+
if (SEED_IF_MISSING_PATTERN.test(relPath)) return false;
|
|
1823
1833
|
return PROTECTED_PATTERNS.some((re) => re.test(relPath));
|
|
1824
1834
|
}
|
|
1825
1835
|
async function listShippedThemes(templatesRoot) {
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
> English: [README.md](./README.md)
|
|
2
|
+
|
|
3
|
+
# サイトローカルプラグイン
|
|
4
|
+
|
|
5
|
+
このディレクトリは **このサイト専用のプラグイン置き場**。別 npm
|
|
6
|
+
パッケージとして publish したくない小さなカスタマイズを書く場所。
|
|
7
|
+
|
|
8
|
+
`update-ampless` はこのディレクトリのファイルに一切触らない。ここに置いた
|
|
9
|
+
ものは消えない、上書きされない。
|
|
10
|
+
|
|
11
|
+
## いつ使うか
|
|
12
|
+
|
|
13
|
+
サイト固有の機能で、以下に当てはまるときに使う:
|
|
14
|
+
|
|
15
|
+
- プラグイン surface (`publicHead` / `publicBodyEnd` / `metadata` / `eventHooks` 等) が必要
|
|
16
|
+
- このサイト限定の用途 (一度きりのフッタークレジット、サイト特有の JSON-LD 拡張、まだ汎用化したくない analytics スニペット等)
|
|
17
|
+
- 別パッケージとして version 上げて publish するのは大袈裟
|
|
18
|
+
|
|
19
|
+
複数サイトで使いたくなったら、独立 npm パッケージに切り出す (Phase 5 で
|
|
20
|
+
`npx create-ampless plugin --standalone` が来る予定。今は手でコピーで OK)。
|
|
21
|
+
|
|
22
|
+
## 最小例
|
|
23
|
+
|
|
24
|
+
`plugins/footer-credit/index.ts`:
|
|
25
|
+
|
|
26
|
+
```typescript
|
|
27
|
+
import { definePlugin, type AmplessPlugin } from 'ampless'
|
|
28
|
+
|
|
29
|
+
export interface FooterCreditOptions {
|
|
30
|
+
instanceId?: string
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export default function footerCreditPlugin(
|
|
34
|
+
options: FooterCreditOptions = {}
|
|
35
|
+
): AmplessPlugin {
|
|
36
|
+
const instanceId = options.instanceId ?? 'footer-credit'
|
|
37
|
+
return definePlugin({
|
|
38
|
+
name: 'footer-credit',
|
|
39
|
+
instanceId,
|
|
40
|
+
apiVersion: 1,
|
|
41
|
+
trust_level: 'untrusted',
|
|
42
|
+
displayName: { en: 'Footer credit', ja: 'フッタークレジット' },
|
|
43
|
+
capabilities: ['publicBody', 'adminSettings'],
|
|
44
|
+
settings: {
|
|
45
|
+
public: [
|
|
46
|
+
{
|
|
47
|
+
type: 'text',
|
|
48
|
+
key: 'html',
|
|
49
|
+
label: { en: 'Snippet', ja: 'スニペット' },
|
|
50
|
+
default: '',
|
|
51
|
+
},
|
|
52
|
+
],
|
|
53
|
+
},
|
|
54
|
+
publicBodyEnd(ctx) {
|
|
55
|
+
const html = (ctx.setting<string>('html') ?? '').trim()
|
|
56
|
+
if (!html) return []
|
|
57
|
+
return [{ type: 'noscript', id: `footer-credit-${instanceId}`, html }]
|
|
58
|
+
},
|
|
59
|
+
})
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`cms.config.ts` で register:
|
|
64
|
+
|
|
65
|
+
```typescript
|
|
66
|
+
import footerCreditPlugin from './plugins/footer-credit'
|
|
67
|
+
|
|
68
|
+
export default defineConfig({
|
|
69
|
+
// ...
|
|
70
|
+
plugins: [
|
|
71
|
+
// ...既存 plugin...
|
|
72
|
+
footerCreditPlugin(),
|
|
73
|
+
],
|
|
74
|
+
})
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
これだけ。`next dev` 再起動 → `/admin/plugins` でスニペットを設定すれば、
|
|
78
|
+
すべての公開ページの `</body>` 直前にレンダされる。
|
|
79
|
+
|
|
80
|
+
## 宣言できる surface
|
|
81
|
+
|
|
82
|
+
プラグインは `definePlugin({...})` で組み立てるただのオブジェクト。型は
|
|
83
|
+
`node_modules/ampless/dist/plugin.d.ts` を見るか、[プラグイン作者ガイド][guide]
|
|
84
|
+
の散文で。
|
|
85
|
+
|
|
86
|
+
現状 active な capability:
|
|
87
|
+
|
|
88
|
+
| capability | 用途 |
|
|
89
|
+
|---|---|
|
|
90
|
+
| `publicHead` | `<head>` に site-wide で挿入される descriptor |
|
|
91
|
+
| `publicBody` | `</body>` 直前に site-wide で挿入される descriptor |
|
|
92
|
+
| `metadata` | post ごとの Next.js Metadata 拡張 |
|
|
93
|
+
| `eventHooks` | trusted/untrusted の背景ハンドラ (content lifecycle / media event 等) |
|
|
94
|
+
| `adminSettings` | `settings.public[]` で宣言する admin 編集可能な設定 |
|
|
95
|
+
| `writePublicAsset` | trusted plugin が `public/plugins/<instanceId>/...` に書き込み |
|
|
96
|
+
| `schema` | post ごとの JSON-LD を `publicBodyForPost` 経由で (テーマ側で `ampless.publicBodyForPost(post)` を呼ぶ前提) |
|
|
97
|
+
|
|
98
|
+
[guide]: https://github.com/heavymoons/ampless/blob/main/packages/ampless/docs/plugin-author-guide.md
|
|
99
|
+
|
|
100
|
+
## TypeScript 設定
|
|
101
|
+
|
|
102
|
+
`tsconfig.json` の `**/*.ts` include glob でこのディレクトリも自動的に
|
|
103
|
+
カバーされている。`import x from './plugins/foo'` も
|
|
104
|
+
`import x from '@/plugins/foo'` も追加設定なしで動く。
|
|
105
|
+
|
|
106
|
+
## `update-ampless` はどうなるか
|
|
107
|
+
|
|
108
|
+
何もしない。`plugins/` は upgrade ツールの protected list に入っているので、
|
|
109
|
+
ここに置いたファイルは上書きも削除もされない。代償として **この README
|
|
110
|
+
も更新されない** — プラグイン API に大きな変更があるときは、本家リポジトリの
|
|
111
|
+
[プラグイン作者ガイド][guide] で最新版を確認すること。
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
> 日本語版: [README.ja.md](./README.ja.md)
|
|
2
|
+
|
|
3
|
+
# Site-local plugins
|
|
4
|
+
|
|
5
|
+
This directory is for **plugins that belong only to this site** — small
|
|
6
|
+
customizations you don't want to publish as a separate npm package.
|
|
7
|
+
|
|
8
|
+
`update-ampless` never touches files in this directory, so anything you
|
|
9
|
+
add here is yours to keep.
|
|
10
|
+
|
|
11
|
+
## When to use a local plugin
|
|
12
|
+
|
|
13
|
+
Reach for a local plugin when you want a site-specific feature that:
|
|
14
|
+
|
|
15
|
+
- needs the plugin surface (`publicHead` / `publicBodyEnd` / `metadata` / `eventHooks` / etc.)
|
|
16
|
+
- is specific to this site (a one-off footer credit, a custom JSON-LD enrichment, an analytics snippet you're not yet ready to ship as a reusable package)
|
|
17
|
+
- you'd rather not version-bump or republish to iterate on
|
|
18
|
+
|
|
19
|
+
When the plugin grows useful for more than one site, lift it into its
|
|
20
|
+
own npm package (see `npx create-ampless plugin --standalone` once it
|
|
21
|
+
ships in Phase 5; for now you can copy it out by hand).
|
|
22
|
+
|
|
23
|
+
## Minimal example
|
|
24
|
+
|
|
25
|
+
`plugins/footer-credit/index.ts`:
|
|
26
|
+
|
|
27
|
+
```typescript
|
|
28
|
+
import { definePlugin, type AmplessPlugin } from 'ampless'
|
|
29
|
+
|
|
30
|
+
export interface FooterCreditOptions {
|
|
31
|
+
instanceId?: string
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
export default function footerCreditPlugin(
|
|
35
|
+
options: FooterCreditOptions = {}
|
|
36
|
+
): AmplessPlugin {
|
|
37
|
+
const instanceId = options.instanceId ?? 'footer-credit'
|
|
38
|
+
return definePlugin({
|
|
39
|
+
name: 'footer-credit',
|
|
40
|
+
instanceId,
|
|
41
|
+
apiVersion: 1,
|
|
42
|
+
trust_level: 'untrusted',
|
|
43
|
+
displayName: { en: 'Footer credit', ja: 'フッタークレジット' },
|
|
44
|
+
capabilities: ['publicBody', 'adminSettings'],
|
|
45
|
+
settings: {
|
|
46
|
+
public: [
|
|
47
|
+
{
|
|
48
|
+
type: 'text',
|
|
49
|
+
key: 'html',
|
|
50
|
+
label: { en: 'Snippet', ja: 'スニペット' },
|
|
51
|
+
default: '',
|
|
52
|
+
},
|
|
53
|
+
],
|
|
54
|
+
},
|
|
55
|
+
publicBodyEnd(ctx) {
|
|
56
|
+
const html = (ctx.setting<string>('html') ?? '').trim()
|
|
57
|
+
if (!html) return []
|
|
58
|
+
return [{ type: 'noscript', id: `footer-credit-${instanceId}`, html }]
|
|
59
|
+
},
|
|
60
|
+
})
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Register it in `cms.config.ts`:
|
|
65
|
+
|
|
66
|
+
```typescript
|
|
67
|
+
import footerCreditPlugin from './plugins/footer-credit'
|
|
68
|
+
|
|
69
|
+
export default defineConfig({
|
|
70
|
+
// ...
|
|
71
|
+
plugins: [
|
|
72
|
+
// ...existing plugins...
|
|
73
|
+
footerCreditPlugin(),
|
|
74
|
+
],
|
|
75
|
+
})
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
That's it. Restart `next dev` and visit `/admin/plugins` to configure
|
|
79
|
+
the snippet, then any public page renders it before `</body>`.
|
|
80
|
+
|
|
81
|
+
## What you can declare
|
|
82
|
+
|
|
83
|
+
A plugin is just an object built with `definePlugin({...})`. The full
|
|
84
|
+
shape lives in `node_modules/ampless/dist/plugin.d.ts` (or [the plugin
|
|
85
|
+
author guide][guide] if you prefer prose).
|
|
86
|
+
|
|
87
|
+
Capabilities currently active:
|
|
88
|
+
|
|
89
|
+
| capability | purpose |
|
|
90
|
+
|---|---|
|
|
91
|
+
| `publicHead` | descriptors rendered in `<head>` site-wide |
|
|
92
|
+
| `publicBody` | descriptors rendered before `</body>` site-wide |
|
|
93
|
+
| `metadata` | per-post Next.js Metadata contributions |
|
|
94
|
+
| `eventHooks` | trusted/untrusted background handlers (content lifecycle, media events, ...) |
|
|
95
|
+
| `adminSettings` | admin-editable settings declared via `settings.public[]` |
|
|
96
|
+
| `writePublicAsset` | trusted plugins can write namespaced files under `public/plugins/<instanceId>/...` |
|
|
97
|
+
| `schema` | per-post JSON-LD via `publicBodyForPost` (theme template must call `ampless.publicBodyForPost(post)`) |
|
|
98
|
+
|
|
99
|
+
[guide]: https://github.com/heavymoons/ampless/blob/main/packages/ampless/docs/plugin-author-guide.md
|
|
100
|
+
|
|
101
|
+
## What about TypeScript?
|
|
102
|
+
|
|
103
|
+
`tsconfig.json` already covers this directory through its `**/*.ts`
|
|
104
|
+
include glob. Both `import x from './plugins/foo'` and
|
|
105
|
+
`import x from '@/plugins/foo'` work; no extra setup needed.
|
|
106
|
+
|
|
107
|
+
## What `update-ampless` does
|
|
108
|
+
|
|
109
|
+
Nothing. `plugins/` is in the upgrade tool's protected list, so files
|
|
110
|
+
here are never overwritten or deleted on upgrade. The flip side is that
|
|
111
|
+
this README does not get refreshed either — when ampless ships
|
|
112
|
+
significant changes to the plugin API, check the [plugin author guide][guide]
|
|
113
|
+
in the canonical repo for the up-to-date version.
|