@pantheon-systems/p1-next-sdk 0.24.0 → 0.25.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 +17 -1
- package/bin/lib/cli.js +143 -25
- package/bin/lib/detect.js +14 -2
- package/bin/lib/fs-ops.js +2 -1
- package/bin/lib/localized-pages.js +522 -0
- package/bin/lib/messages.js +38 -23
- package/bin/templates/localized-pages/app/[[...puckPath]]/layout.tsx.template +29 -0
- package/bin/templates/localized-pages/app/[[...puckPath]]/page.tsx.template +24 -0
- package/bin/templates/localized-pages/app/p1/layout.tsx.template +11 -0
- package/bin/templates/localized-pages/components/html-shell.tsx.template +28 -0
- package/bin/templates/localized-pages/components/locale-suggestion.module.css.template +74 -0
- package/bin/templates/localized-pages/components/locale-suggestion.tsx.template +94 -0
- package/bin/templates/localized-pages/legacy/app/[...puckPath]/page.tsx.template +23 -0
- package/bin/templates/localized-pages/legacy/app/layout.tsx.template +37 -0
- package/bin/templates/localized-pages/legacy/app/layout.v1.tsx.template +27 -0
- package/bin/templates/localized-pages/legacy/app/page.tsx.template +19 -0
- package/bin/templates/localized-pages/lib/locale-name.ts.template +9 -0
- package/dist/pages-handler.js +2 -2
- package/docs/migrations/editor-layout.md +213 -0
- package/docs/migrations/localized-pages.md +208 -0
- package/package.json +4 -3
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
# Migration Guide: Localized Published Pages
|
|
2
|
+
|
|
3
|
+
This guide covers moving an existing starter-kit project to the published-page layout that new projects from `create-p1-starter-kit@0.24.x` have: the home page and every published page served by one optional catch-all route, under a root layout that sets `<html lang>` to the language of the page shown. It needs `@pantheon-systems/p1-next-sdk@0.24.0` or newer.
|
|
4
|
+
|
|
5
|
+
New projects already have this structure. This guide is only for **existing projects**.
|
|
6
|
+
|
|
7
|
+
## Breaking: one optional catch-all and two root layouts
|
|
8
|
+
|
|
9
|
+
The site's routes move from `app/page.tsx` plus `app/[...puckPath]/` to a single `app/[[...puckPath]]/`, which serves `/` too. `<html lang>` has to come from the page being shown, so the single `app/layout.tsx` is replaced by two root layouts: `app/[[...puckPath]]/layout.tsx` for the site and `app/p1/layout.tsx` for the editor. Both render the `<html>` and `<body>` from `components/html-shell.tsx`.
|
|
10
|
+
|
|
11
|
+
> **Nothing fails if you skip this.** A project left on the old layout keeps rendering, with `<html lang="en">` on every page. Pages on a site with locales still get their `hreflang` alternates and `useP1Localization()` still works, because both come from the SDK. Migrate when you want each page's language in its `<html>`.
|
|
12
|
+
|
|
13
|
+
## Recommended: run the codemod
|
|
14
|
+
|
|
15
|
+
From your project root, on a clean git tree:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npx @pantheon-systems/p1-next-sdk migrate localized-pages --dry-run # preview
|
|
19
|
+
npx @pantheon-systems/p1-next-sdk migrate localized-pages # apply
|
|
20
|
+
npx @pantheon-systems/p1-next-sdk migrate locale-prompt # optional: add the language prompt
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Each migration is its own subcommand and changes only its own files; `npx @pantheon-systems/p1-next-sdk migrate` on its own lists them. If your editor is still on `app/p1/[[...p1]]/`, run `migrate editor-layout` too (see the [persistent editor layout](./editor-layout.md) guide). Running a migration a second time changes nothing.
|
|
24
|
+
|
|
25
|
+
It checks the installed P1 packages first and stops, saying so, when they are older than 0.24.0. It refuses to run on a dirty tree unless you pass `--force`, plans every file before writing any, and **bails with a pointer back to this guide** when a file it would replace or delete differs from the starter's. It replaces `app/layout.tsx` and the catch-all's `page.tsx`, and deletes `app/page.tsx`, only when they match a scaffolded version; for a customized layout it lists what to carry across. It also deletes the tests earlier starters scaffolded and current ones no longer include (`__tests__/published-page-routes.test.ts`, `widget-logout.test.ts`, `styles-canvas-scope.test.ts` and `editor-route-group.test.ts`) when they match a scaffolded version, and stops on any you changed. If it bails, follow the manual steps below.
|
|
26
|
+
|
|
27
|
+
`migrate locale-prompt` adds the starter's saved-language prompt once `localized-pages` has run: it copies `components/locale-suggestion.tsx`, `components/locale-suggestion.module.css` and `lib/locale-name.ts` from the starter and renders the prompt from your page client (step 5). Skip it if you do not want the prompt or will build your own.
|
|
28
|
+
|
|
29
|
+
It warns, without changing anything, when `app/p1/api/[...p1]/route.ts` passes `publicPageSegment: "/[...puckPath]"`, and when other files in your project, such as tests, still name `app/[...puckPath]/`.
|
|
30
|
+
|
|
31
|
+
Review the diff and commit it as its own change.
|
|
32
|
+
|
|
33
|
+
## Manual steps
|
|
34
|
+
|
|
35
|
+
### 1. Move the catch-all and the 404 page
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
app/[...puckPath]/ -> app/[[...puckPath]]/
|
|
39
|
+
app/not-found.tsx -> app/[[...puckPath]]/not-found.tsx
|
|
40
|
+
app/page.tsx (delete)
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The catch-all keeps its depth, so the files in it keep their imports. It now serves `/` too, where `params.puckPath` is `undefined`, so check that anything you changed in its `page.tsx` handles the home page. `not-found.tsx` moves one directory deeper, so its imports do too:
|
|
44
|
+
|
|
45
|
+
```diff
|
|
46
|
+
-import { PageMissing } from "../components/page-missing";
|
|
47
|
+
+import { PageMissing } from "../../components/page-missing";
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
`app/[[...puckPath]]` matches `/`, so `app/page.tsx` has to go: Next.js refuses two routes for the same path. The catch-all's `published.Page` renders the home page, and the `titles.home` and `Fallback` options you pass to `createPublishedPage` still apply. If you added anything to `app/page.tsx`, move it into your published content or the page client first.
|
|
51
|
+
|
|
52
|
+
Any `error.tsx`, `loading.tsx` or `template.tsx` in `app/` or in the old catch-all now sits beside a different root layout. Decide where each belongs: `app/[[...puckPath]]/` for the site, `app/p1/` for the editor.
|
|
53
|
+
|
|
54
|
+
### 2. Point the shared module at the new directory
|
|
55
|
+
|
|
56
|
+
`app/published-pages.tsx`:
|
|
57
|
+
|
|
58
|
+
```diff
|
|
59
|
+
-import { Client } from "./[...puckPath]/client";
|
|
60
|
+
+import { Client } from "./[[...puckPath]]/client";
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### 3. Split the root layout in two
|
|
64
|
+
|
|
65
|
+
Move the `<html>` and `<body>` from `app/layout.tsx` into `components/html-shell.tsx`, taking the language as a prop:
|
|
66
|
+
|
|
67
|
+
```tsx
|
|
68
|
+
export function HtmlShell({
|
|
69
|
+
lang,
|
|
70
|
+
children,
|
|
71
|
+
}: {
|
|
72
|
+
lang: string;
|
|
73
|
+
children: React.ReactNode;
|
|
74
|
+
}) {
|
|
75
|
+
return (
|
|
76
|
+
<html lang={lang}>
|
|
77
|
+
<body data-rm-theme="light">
|
|
78
|
+
<div className="p1-app-shell">{children}</div>
|
|
79
|
+
</body>
|
|
80
|
+
</html>
|
|
81
|
+
);
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Add the site's root layout, `app/[[...puckPath]]/layout.tsx`. It takes over the `metadata` export from `app/layout.tsx`:
|
|
86
|
+
|
|
87
|
+
```tsx
|
|
88
|
+
import "../styles.css";
|
|
89
|
+
import type { Metadata } from "next";
|
|
90
|
+
import { HtmlShell } from "../../components/html-shell";
|
|
91
|
+
import { published } from "../published-pages";
|
|
92
|
+
|
|
93
|
+
const siteUrl = process.env.NEXT_PUBLIC_SITE_URL;
|
|
94
|
+
|
|
95
|
+
export const metadata: Metadata = {
|
|
96
|
+
...(siteUrl ? { metadataBase: new URL(siteUrl) } : {}),
|
|
97
|
+
openGraph: {
|
|
98
|
+
type: "website",
|
|
99
|
+
siteName: process.env.NEXT_PUBLIC_SITE_NAME,
|
|
100
|
+
},
|
|
101
|
+
};
|
|
102
|
+
|
|
103
|
+
export default async function SiteLayout({
|
|
104
|
+
children,
|
|
105
|
+
params,
|
|
106
|
+
}: {
|
|
107
|
+
children: React.ReactNode;
|
|
108
|
+
params: Promise<{ puckPath?: string[] }>;
|
|
109
|
+
}) {
|
|
110
|
+
const lang = (await published.getDocumentLanguage({ params })) ?? "en";
|
|
111
|
+
return <HtmlShell lang={lang}>{children}</HtmlShell>;
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Add the editor's root layout, `app/p1/layout.tsx`:
|
|
116
|
+
|
|
117
|
+
```tsx
|
|
118
|
+
import "../styles.css";
|
|
119
|
+
import { HtmlShell } from "../../components/html-shell";
|
|
120
|
+
|
|
121
|
+
export default function EditorRootLayout({
|
|
122
|
+
children,
|
|
123
|
+
}: {
|
|
124
|
+
children: React.ReactNode;
|
|
125
|
+
}) {
|
|
126
|
+
return <HtmlShell lang="en">{children}</HtmlShell>;
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Then delete `app/layout.tsx`. If you customized it, carry each change to where it now belongs:
|
|
131
|
+
|
|
132
|
+
| In your `app/layout.tsx` | Moves to |
|
|
133
|
+
| --- | --- |
|
|
134
|
+
| Fonts (`next/font`), providers, wrappers, analytics and other scripts | `components/html-shell.tsx`, so both the site and the editor get them |
|
|
135
|
+
| `metadata`, `metadataBase`, `viewport` | `app/[[...puckPath]]/layout.tsx` |
|
|
136
|
+
| Anything only the editor needs | `app/p1/layout.tsx` |
|
|
137
|
+
|
|
138
|
+
Every page needs a root layout, so any other page directly under `app/` (outside `app/p1/` and `app/[[...puckPath]]/`) needs a `layout.tsx` of its own that renders `HtmlShell`, in its directory or a route group above it, such as `app/(marketing)/layout.tsx`.
|
|
139
|
+
|
|
140
|
+
### 4. Leave the route refresh to the SDK
|
|
141
|
+
|
|
142
|
+
Publishing a route template refreshes every page under the public catch-all, and by default the SDK refreshes both `/[...puckPath]` and `/[[...puckPath]]`. If `app/p1/api/[...p1]/route.ts` passes `publicPageSegment`, remove it or set it to the new directory:
|
|
143
|
+
|
|
144
|
+
```diff
|
|
145
|
+
const handler = createP1Handler({
|
|
146
|
+
…
|
|
147
|
+
- publicPageSegment: "/[...puckPath]",
|
|
148
|
+
});
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### 5. Optional: add the saved-language prompt
|
|
152
|
+
|
|
153
|
+
Copy `components/locale-suggestion.tsx`, `components/locale-suggestion.module.css` and `lib/locale-name.ts` from a new project, then render the prompt from `app/[[...puckPath]]/client.tsx` when it receives a `localization` prop:
|
|
154
|
+
|
|
155
|
+
```diff
|
|
156
|
+
import { RenderClient, performLogout, P1_LOGGED_IN_KEY } from "@pantheon-systems/puck-css";
|
|
157
|
+
+import type { PublishedPageLocalization } from "@pantheon-systems/p1-next-sdk";
|
|
158
|
+
import config from "../../puck.config";
|
|
159
|
+
+import { LocaleSuggestion } from "../../components/locale-suggestion";
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
```diff
|
|
163
|
+
export function Client({
|
|
164
|
+
data,
|
|
165
|
+
pageMetadata,
|
|
166
|
+
+ localization,
|
|
167
|
+
}: {
|
|
168
|
+
data: Data;
|
|
169
|
+
pageMetadata?: { … };
|
|
170
|
+
+ localization?: PublishedPageLocalization;
|
|
171
|
+
}) {
|
|
172
|
+
return (
|
|
173
|
+
<>
|
|
174
|
+
<RenderClient config={config} data={data} />
|
|
175
|
+
+ {localization && <LocaleSuggestion />}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
### 6. Update your own references
|
|
179
|
+
|
|
180
|
+
Tests and other files that import from or read `app/[...puckPath]/`, `app/page.tsx` or `app/layout.tsx` need the new paths. Delete `__tests__/published-page-routes.test.ts`, `widget-logout.test.ts`, `styles-canvas-scope.test.ts` and `editor-route-group.test.ts` if your project has them: newer starters no longer include them, and they read files at the old paths. To keep one, rename it and update its paths.
|
|
181
|
+
|
|
182
|
+
## Minimum structure after migration
|
|
183
|
+
|
|
184
|
+
```
|
|
185
|
+
app/
|
|
186
|
+
[[...puckPath]]/
|
|
187
|
+
layout.tsx # site root layout: <html lang> from getDocumentLanguage
|
|
188
|
+
page.tsx # re-exports published.Page / generateMetadata / generateStaticParams
|
|
189
|
+
client.tsx
|
|
190
|
+
not-found.tsx
|
|
191
|
+
p1/
|
|
192
|
+
layout.tsx # editor root layout
|
|
193
|
+
(editor)/…
|
|
194
|
+
api/[...p1]/route.ts
|
|
195
|
+
published-pages.tsx # createPublishedPage({ … })
|
|
196
|
+
styles.css
|
|
197
|
+
components/
|
|
198
|
+
html-shell.tsx # <html> and <body> for both root layouts
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
No `app/layout.tsx` and no `app/page.tsx`.
|
|
202
|
+
|
|
203
|
+
## Check the result
|
|
204
|
+
|
|
205
|
+
- `next build` lists `● /[[...puckPath]]` as statically generated, and no `ƒ /`.
|
|
206
|
+
- On a site with locales, a localized page's `<html lang>` matches its locale.
|
|
207
|
+
- Navigating between `/` and another page updates `lang` without a full reload.
|
|
208
|
+
- Publishing a route template refreshes an instance URL such as `/jedi/5`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pantheon-systems/p1-next-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.25.0",
|
|
4
4
|
"license": "UNLICENSED",
|
|
5
5
|
"description": "Next.js SDK for P1 editor integration",
|
|
6
6
|
"publishConfig": {
|
|
@@ -41,14 +41,15 @@
|
|
|
41
41
|
"files": [
|
|
42
42
|
"dist",
|
|
43
43
|
"bin",
|
|
44
|
+
"docs",
|
|
44
45
|
"src/**/*.css",
|
|
45
46
|
"!src/**/*.module.css",
|
|
46
47
|
"!dist/**/*.map"
|
|
47
48
|
],
|
|
48
49
|
"dependencies": {
|
|
49
|
-
"@pantheon-systems/css-client": "0.
|
|
50
|
+
"@pantheon-systems/css-client": "0.25.0",
|
|
50
51
|
"@pantheon-systems/p1-ai-chat": "0.10.0",
|
|
51
|
-
"@pantheon-systems/puck-css": "0.
|
|
52
|
+
"@pantheon-systems/puck-css": "0.25.0",
|
|
52
53
|
"cookie": "^1.1.1",
|
|
53
54
|
"launchdarkly-js-client-sdk": "^3.9.3",
|
|
54
55
|
"server-only": "^0.0.1"
|