create-harper 1.11.7 → 1.12.1

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.
Files changed (50) hide show
  1. package/lib/init.js +1 -1
  2. package/lib/pkg/getWorkflowSubstitutions.js +188 -0
  3. package/lib/steps/scaffoldProject.js +9 -2
  4. package/package.json +2 -2
  5. package/template-nextjs/README.md +27 -3
  6. package/template-nextjs/_github/workflows/deploy.yaml +62 -0
  7. package/template-nextjs-ts/README.md +27 -3
  8. package/template-nextjs-ts/_github/workflows/deploy.yaml +62 -0
  9. package/template-react/README.md +47 -5
  10. package/template-react/_github/workflows/deploy.yaml +63 -0
  11. package/template-react/package.json +2 -1
  12. package/template-react-ssr/README.md +47 -5
  13. package/template-react-ssr/_github/workflows/deploy.yaml +63 -0
  14. package/template-react-ssr/package.json +2 -1
  15. package/template-react-ts/README.md +47 -5
  16. package/template-react-ts/_github/workflows/deploy.yaml +63 -0
  17. package/template-react-ts/package.json +2 -1
  18. package/template-react-ts-ssr/README.md +47 -5
  19. package/template-react-ts-ssr/_github/workflows/deploy.yaml +63 -0
  20. package/template-react-ts-ssr/package.json +2 -1
  21. package/template-vanilla/README.md +47 -5
  22. package/template-vanilla/_github/workflows/deploy.yaml +63 -0
  23. package/template-vanilla/package.json +2 -1
  24. package/template-vanilla-ts/README.md +47 -5
  25. package/template-vanilla-ts/_github/workflows/deploy.yaml +63 -0
  26. package/template-vanilla-ts/package.json +2 -1
  27. package/template-vue/README.md +47 -5
  28. package/template-vue/_github/workflows/deploy.yaml +63 -0
  29. package/template-vue/package.json +2 -1
  30. package/template-vue-ssr/README.md +47 -5
  31. package/template-vue-ssr/_github/workflows/deploy.yaml +63 -0
  32. package/template-vue-ssr/package.json +2 -1
  33. package/template-vue-ts/README.md +47 -5
  34. package/template-vue-ts/_github/workflows/deploy.yaml +63 -0
  35. package/template-vue-ts/package.json +2 -1
  36. package/template-vue-ts-ssr/README.md +47 -5
  37. package/template-vue-ts-ssr/_github/workflows/deploy.yaml +63 -0
  38. package/template-vue-ts-ssr/package.json +2 -1
  39. package/template-nextjs/_github/workflow/deploy.yaml +0 -31
  40. package/template-nextjs-ts/_github/workflow/deploy.yaml +0 -31
  41. package/template-react/_github/workflow/deploy.yaml +0 -33
  42. package/template-react-ssr/_github/workflow/deploy.yaml +0 -33
  43. package/template-react-ts/_github/workflow/deploy.yaml +0 -33
  44. package/template-react-ts-ssr/_github/workflow/deploy.yaml +0 -33
  45. package/template-vanilla/_github/workflow/deploy.yaml +0 -33
  46. package/template-vanilla-ts/_github/workflow/deploy.yaml +0 -33
  47. package/template-vue/_github/workflow/deploy.yaml +0 -33
  48. package/template-vue-ssr/_github/workflow/deploy.yaml +0 -33
  49. package/template-vue-ts/_github/workflow/deploy.yaml +0 -33
  50. package/template-vue-ts-ssr/_github/workflow/deploy.yaml +0 -33
package/lib/init.js CHANGED
@@ -76,7 +76,7 @@ export async function init() {
76
76
  // Write out the contents based on all prior steps.
77
77
  const cwd = process.cwd();
78
78
  const root = path.join(cwd, targetDir);
79
- scaffoldProject(root, projectName, packageName, template, envVars, pkgManager);
79
+ scaffoldProject(root, projectName, packageName, template, envVars, pkgManager, pkgInfo?.version);
80
80
 
81
81
  // Log out the next steps.
82
82
  installAndOptionallyStart(root, pkgManager, immediate, args.skipInstall, selectedSkills, selectedAgents);
@@ -0,0 +1,188 @@
1
+ // Indentation of the scaffolded GitHub Actions workflows (2-space YAML, so a `steps:` entry's
2
+ // `-` sits six columns in). Each multi-line value below replaces a placeholder comment that
3
+ // already sits at that indent, so a value's *first* line carries no indentation and every
4
+ // continuation line carries it explicitly.
5
+ const STEP_INDENT = ' '.repeat(6);
6
+ const KEY_INDENT = ' '.repeat(2);
7
+ const INPUT_INDENT = ' '.repeat(4);
8
+
9
+ /**
10
+ * Builds one `steps:` entry, or a bare comment when a package manager needs no setup step.
11
+ *
12
+ * @param {{name?: string, comment?: string[], uses?: string, inputs?: Record<string, string>, run?: string}} step
13
+ * @returns {string} - The step's YAML, indented for substitution into the workflow.
14
+ */
15
+ function buildStep({ name, comment, uses, inputs, run }) {
16
+ const lines = [];
17
+ if (name) { lines.push(`- name: ${name}`); }
18
+ for (const line of comment ?? []) {
19
+ // A comment-only value stands in for a step, so it starts at the step indent; a comment
20
+ // documenting a step is nested with that step's other keys.
21
+ lines.push(`${name ? KEY_INDENT : ''}# ${line}`);
22
+ }
23
+ if (uses) { lines.push(`${KEY_INDENT}uses: ${uses}`); }
24
+ if (inputs) {
25
+ lines.push(`${KEY_INDENT}with:`);
26
+ for (const [input, value] of Object.entries(inputs)) {
27
+ lines.push(`${INPUT_INDENT}${input}: ${value}`);
28
+ }
29
+ }
30
+ if (run) { lines.push(`${KEY_INDENT}run: ${run}`); }
31
+ return lines.join(`\n${STEP_INDENT}`);
32
+ }
33
+
34
+ /**
35
+ * Extracts the major version from a package manager version string.
36
+ *
37
+ * @param {string | undefined} version - A version such as '4.9.1'.
38
+ * @returns {number | undefined} - The major version, or undefined if it can't be determined.
39
+ */
40
+ function majorVersion(version) {
41
+ const major = Number.parseInt(version ?? '', 10);
42
+ return Number.isNaN(major) ? undefined : major;
43
+ }
44
+
45
+ /**
46
+ * Builds the step that puts the project's package manager on PATH, pinned to the version that
47
+ * generated its lockfile. npm and Yarn 1.x (Classic) need none — npm ships with Node.js, and
48
+ * Classic is preinstalled on GitHub's Ubuntu runners — so they get a comment saying so instead.
49
+ *
50
+ * @param {string} agent - The package manager agent ('npm', 'pnpm', 'yarn', 'bun' or 'deno').
51
+ * @param {string} [version] - The agent's version, as reported by the user agent that invoked us.
52
+ * @returns {string} - The step's YAML.
53
+ */
54
+ function getSetupStep(agent, version) {
55
+ switch (agent) {
56
+ case 'pnpm':
57
+ return buildStep({
58
+ name: 'Set up pnpm',
59
+ comment: [
60
+ "Pinned to the pnpm that wrote this project's lockfile. The action is SHA-pinned, but a",
61
+ 'floating `version:` would still let it self-install an unvetted pnpm at run time.',
62
+ ],
63
+ uses: 'pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9',
64
+ inputs: { version: version ?? 'latest' },
65
+ });
66
+ case 'bun':
67
+ return buildStep({
68
+ name: 'Set up Bun',
69
+ comment: ["Pinned to the Bun that wrote this project's lockfile."],
70
+ uses: 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0',
71
+ inputs: { 'bun-version': version ?? 'latest' },
72
+ });
73
+ case 'deno':
74
+ return buildStep({
75
+ name: 'Set up Deno',
76
+ comment: ["Pinned to the Deno that wrote this project's lockfile."],
77
+ uses: 'denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed # v2.0.5',
78
+ inputs: { 'deno-version': version ?? 'vx.x.x' },
79
+ });
80
+ case 'yarn':
81
+ // Only Yarn 2+ (Berry) needs provisioning. The runner ships Yarn 1.x (Classic), and a
82
+ // scaffolded project pins no `packageManager`/`.yarnrc.yml`, so without this Berry's
83
+ // `--immutable` (below) would run under Classic, which rejects the flag and stops the
84
+ // deploy at install. Corepack activates the exact Yarn that wrote yarn.lock: `enable`
85
+ // installs the shim, `prepare … --activate` sets that version as the default a bare
86
+ // `yarn` resolves to (no `packageManager` field required).
87
+ if ((majorVersion(version) ?? 1) < 2) {
88
+ return buildStep({
89
+ comment: ["Yarn 1.x (Classic) is preinstalled on GitHub's Ubuntu runners, so it needs no setup step."],
90
+ });
91
+ }
92
+ return buildStep({
93
+ name: `Set up Yarn ${version}`,
94
+ comment: ["Pinned to the Yarn that wrote this project's lockfile."],
95
+ run: `corepack enable && corepack prepare yarn@${version} --activate`,
96
+ });
97
+ default:
98
+ return buildStep({ comment: ['npm ships with Node.js, so it needs no setup step.'] });
99
+ }
100
+ }
101
+
102
+ /**
103
+ * Builds `actions/setup-node`'s `cache:` input. Only npm, Yarn and pnpm are supported there;
104
+ * Bun and Deno cache through their own setup actions, so they get a comment explaining the gap
105
+ * rather than an input setup-node would reject.
106
+ *
107
+ * @param {string} agent - The package manager agent ('npm', 'pnpm', 'yarn', 'bun' or 'deno').
108
+ * @returns {string} - The `cache:` input, or a comment.
109
+ */
110
+ function getNodeCacheInput(agent) {
111
+ switch (agent) {
112
+ case 'bun':
113
+ return "# setup-node caches npm, Yarn and pnpm only; oven-sh/setup-bun caches Bun's store itself.";
114
+ case 'deno':
115
+ return '# setup-node caches npm, Yarn and pnpm only; denoland/setup-deno caches DENO_DIR itself.';
116
+ case 'pnpm':
117
+ case 'yarn':
118
+ return `cache: '${agent}'`;
119
+ default:
120
+ return "cache: 'npm'";
121
+ }
122
+ }
123
+
124
+ /**
125
+ * Gets the lockfile-respecting install command for CI, which must fail rather than update the
126
+ * lockfile when it has drifted from package.json.
127
+ *
128
+ * @param {string} agent - The package manager agent ('npm', 'pnpm', 'yarn', 'bun' or 'deno').
129
+ * @param {string} [version] - The agent's version, as reported by the user agent that invoked us.
130
+ * @returns {string} - The install command.
131
+ */
132
+ function getCiInstallCommand(agent, version) {
133
+ switch (agent) {
134
+ case 'pnpm':
135
+ case 'bun':
136
+ return `${agent} install --frozen-lockfile`;
137
+ case 'yarn':
138
+ // Yarn renamed the flag in 2.0; Yarn 1 rejects `--immutable` and Yarn 2+ rejects
139
+ // `--frozen-lockfile`, so pick by the version that scaffolded the project.
140
+ return (majorVersion(version) ?? 1) >= 2 ? 'yarn install --immutable' : 'yarn install --frozen-lockfile';
141
+ case 'deno':
142
+ return 'deno install --frozen';
143
+ default:
144
+ return 'npm ci';
145
+ }
146
+ }
147
+
148
+ /**
149
+ * Gets the command prefix that runs a package.json script, e.g. `npm run` in `npm run deploy`.
150
+ *
151
+ * @param {string} agent - The package manager agent ('npm', 'pnpm', 'yarn', 'bun' or 'deno').
152
+ * @returns {string} - The prefix, without a trailing space.
153
+ */
154
+ function getRunScriptPrefix(agent) {
155
+ switch (agent) {
156
+ case 'deno':
157
+ return 'deno task';
158
+ case 'pnpm':
159
+ case 'yarn':
160
+ case 'bun':
161
+ return `${agent} run`;
162
+ default:
163
+ return 'npm run';
164
+ }
165
+ }
166
+
167
+ /**
168
+ * Builds the substitutions that adapt a scaffolded project's GitHub Actions workflows to the
169
+ * package manager that invoked us. Without them the workflows would hard-code npm and fail for
170
+ * everyone else: setup-node can't resolve a package lock for a project whose lockfile is
171
+ * `pnpm-lock.yaml`, and `npm ci` errors out before the job ever reaches tests or deploy.
172
+ *
173
+ * Placeholders that stand in for a whole line are written as YAML comments in the templates, so
174
+ * the committed workflows stay valid, formattable YAML; the indentation contract for their
175
+ * multi-line replacements lives in this module.
176
+ *
177
+ * @param {string} agent - The package manager agent ('npm', 'pnpm', 'yarn', 'bun' or 'deno').
178
+ * @param {string} [version] - The agent's version, as reported by the user agent that invoked us.
179
+ * @returns {Record<string, string>} - A mapping of placeholder to replacement.
180
+ */
181
+ export function getWorkflowSubstitutions(agent, version) {
182
+ return {
183
+ '# your-package-manager-setup-step-here': getSetupStep(agent, version),
184
+ '# your-package-manager-node-cache-here': getNodeCacheInput(agent),
185
+ 'your-package-manager-install-here': getCiInstallCommand(agent, version),
186
+ 'your-package-manager-run-here': getRunScriptPrefix(agent),
187
+ };
188
+ }
@@ -3,6 +3,7 @@ import fs from 'node:fs';
3
3
  import path from 'node:path';
4
4
  import { fileURLToPath } from 'node:url';
5
5
  import { crawlTemplateDir } from '../fs/crawlTemplateDir.js';
6
+ import { getWorkflowSubstitutions } from '../pkg/getWorkflowSubstitutions.js';
6
7
 
7
8
  /**
8
9
  * Step 6: Create the project structure and files based on the collected information.
@@ -13,16 +14,22 @@ import { crawlTemplateDir } from '../fs/crawlTemplateDir.js';
13
14
  * @param {string} template - The template name to use.
14
15
  * @param {import('./getEnvVars.js').EnvVars} [envVars] - Environment variables to substitute.
15
16
  * @param {string} [pkgManager] - The package manager that invoked us (e.g. npm, pnpm, yarn, bun). Defaults to npm.
17
+ * @param {string} [pkgManagerVersion] - That package manager's version, used to pin it in CI.
16
18
  */
17
- export function scaffoldProject(root, projectName, packageName, template, envVars, pkgManager) {
19
+ export function scaffoldProject(root, projectName, packageName, template, envVars, pkgManager, pkgManagerVersion) {
18
20
  fs.mkdirSync(root, { recursive: true });
19
21
  prompts.log.step(`Scaffolding project in ${root}...`);
20
22
 
23
+ const agent = pkgManager || 'npm';
21
24
  const substitutions = {
22
25
  'your-project-name-here': projectName || 'your-project-name-here',
23
26
  'your-package-name-here': packageName || 'your-package-name-here',
24
27
  'your-fabric.harper.fast-cluster-url-here': envVars?.target || 'your-fabric.harper.fast-cluster-url-here',
25
- 'your-package-manager-here': pkgManager || 'npm',
28
+ // Substitution runs these keys in order as plain string replaces, so the longer
29
+ // `your-package-manager-*-here` placeholders resolve before the bare one below and can
30
+ // never have their prefix eaten by it.
31
+ ...getWorkflowSubstitutions(agent, pkgManagerVersion),
32
+ 'your-package-manager-here': agent,
26
33
  '\n\t"repository": "github:HarperFast/create-harper",': '',
27
34
  };
28
35
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "create-harper",
3
3
  "description": "Scaffold a new Harper project in JavaScript or TypeScript.",
4
- "version": "1.11.7",
4
+ "version": "1.12.1",
5
5
  "type": "module",
6
6
  "sideEffects": false,
7
7
  "exports": {
@@ -79,7 +79,7 @@
79
79
  "conventional-changelog-conventionalcommits": "^9.3.1",
80
80
  "conventional-commits-filter": "^6.0.1",
81
81
  "conventional-commits-parser": "^7.1.0",
82
- "dprint": "^0.55.0",
82
+ "dprint": "^0.56.0",
83
83
  "oxlint": "^1.38.0",
84
84
  "semantic-release": "^25.0.2",
85
85
  "vitest": "^4.0.17"
@@ -19,7 +19,7 @@ npm install -g harper
19
19
  Start the app:
20
20
 
21
21
  ```sh
22
- npm run dev
22
+ your-package-manager-run-here dev
23
23
  ```
24
24
 
25
25
  Then open [http://localhost:9926](http://localhost:9926) 🎉
@@ -67,10 +67,34 @@ harper login
67
67
  Then deploy your app:
68
68
 
69
69
  ```sh
70
- npm run deploy
70
+ your-package-manager-run-here deploy
71
71
  ```
72
72
 
73
- `npm run deploy` runs `next build` locally and ships the prebuilt `.next` output, then Harper serves it — no build runs on the cluster. (Building on the cluster currently fails; see the note in [`config.yaml`](./config.yaml).)
73
+ `your-package-manager-run-here deploy` runs `next build` locally and ships the prebuilt `.next` output, then Harper serves it — no build runs on the cluster. (Building on the cluster currently fails; see the note in [`config.yaml`](./config.yaml).)
74
+
75
+ ### Deploy automatically from CI
76
+
77
+ The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) builds and deploys whenever you push a version tag:
78
+
79
+ ```sh
80
+ git tag v1.0.0
81
+ git push --tags
82
+ ```
83
+
84
+ Add these repository secrets first, under **Settings → Secrets and variables → Actions**:
85
+
86
+ - `HARPER_CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`)
87
+ - `HARPER_CLI_REFRESH_TOKEN` — a long-lived token CI authenticates with, so no password is stored
88
+
89
+ Set both in one command — this pipes the credentials straight from your cluster into GitHub, so the token never appears on screen or in your shell history:
90
+
91
+ ```sh
92
+ harper login --for-ci | gh secret set --env-file -
93
+ ```
94
+
95
+ (No [`gh` CLI](https://cli.github.com)? `harper login --for-ci | pbcopy` copies the two lines for you to paste in by hand.)
96
+
97
+ > **Why this template deploys differently.** The other create-harper templates deploy _by reference_: the cluster clones your repo at a pinned commit and builds there. Next.js can't do that yet — `.next` is gitignored, so a git reference carries no build output, and an on-cluster build currently fails ([nextjs#57](https://github.com/HarperFast/nextjs/issues/57), [nextjs#58](https://github.com/HarperFast/nextjs/issues/58)). Until those land, this template uploads the build itself.
74
98
 
75
99
  ## Keep Going!
76
100
 
@@ -0,0 +1,62 @@
1
+ # Deploys this app to your Harper cluster by *payload* via `harper deploy_component .`
2
+ # (`your-package-manager-run-here deploy`), which runs `next build` first and uploads the prebuilt
3
+ # `.next` output.
4
+ #
5
+ # The other create-harper templates deploy by *reference* (`harper deploy by_ref=true`), where the
6
+ # cluster clones your repo and builds on the node. Next.js can't use that yet: `.next` is gitignored
7
+ # (so a git reference carries no build output) and building on the cluster currently fails —
8
+ # Turbopack crashes inside a Harper worker thread (HarperFast/nextjs#57) and a webpack build
9
+ # overruns the component-load timeout (HarperFast/nextjs#58). Once those land, this template can
10
+ # switch to the by-reference workflow like the rest.
11
+ #
12
+ # Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually.
13
+ #
14
+ # Required repository secrets (Settings → Secrets and variables → Actions):
15
+ # HARPER_CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925
16
+ # HARPER_CLI_REFRESH_TOKEN a long-lived refresh token; the CLI mints a short-lived operation
17
+ # token from it on each run, so no password is stored in CI
18
+ #
19
+ # Set both in one command — this pipes them straight from your cluster into GitHub, so the token
20
+ # never appears on screen or in your shell history:
21
+ #
22
+ # harper login --for-ci | gh secret set --env-file -
23
+ name: Deploy to Harper Fabric
24
+ on:
25
+ workflow_dispatch:
26
+ push:
27
+ tags:
28
+ - 'v*'
29
+
30
+ concurrency:
31
+ group: deploy
32
+ cancel-in-progress: false
33
+
34
+ jobs:
35
+ deploy:
36
+ runs-on: ubuntu-latest
37
+ steps:
38
+ - name: Checkout code
39
+ uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
40
+ with:
41
+ fetch-depth: 0
42
+ fetch-tags: true
43
+ # your-package-manager-setup-step-here
44
+ - name: Set up Node.js
45
+ uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
46
+ with:
47
+ # your-package-manager-node-cache-here
48
+ node-version-file: '.nvmrc'
49
+ - name: Install dependencies
50
+ run: your-package-manager-install-here
51
+ - name: Run lint
52
+ run: your-package-manager-run-here lint
53
+ - name: Install Harper CLI
54
+ # Installed with npm regardless of this project's package manager: it is a global tool, and
55
+ # npm always comes with the Node.js set up above. Pinned to the 5.2 line; ^5.2.0 blocks a
56
+ # breaking 6.x bump.
57
+ run: npm install -g harper@^5.2.0
58
+ - name: Build & deploy
59
+ run: your-package-manager-run-here deploy
60
+ env:
61
+ HARPER_CLI_TARGET: ${{ secrets.HARPER_CLI_TARGET }}
62
+ HARPER_CLI_REFRESH_TOKEN: ${{ secrets.HARPER_CLI_REFRESH_TOKEN }}
@@ -19,7 +19,7 @@ npm install -g harper
19
19
  Start the app:
20
20
 
21
21
  ```sh
22
- npm run dev
22
+ your-package-manager-run-here dev
23
23
  ```
24
24
 
25
25
  Then open [http://localhost:9926](http://localhost:9926) 🎉
@@ -67,10 +67,34 @@ harper login
67
67
  Then deploy your app:
68
68
 
69
69
  ```sh
70
- npm run deploy
70
+ your-package-manager-run-here deploy
71
71
  ```
72
72
 
73
- `npm run deploy` runs `next build` locally and ships the prebuilt `.next` output, then Harper serves it — no build runs on the cluster. (Building on the cluster currently fails; see the note in [`config.yaml`](./config.yaml).)
73
+ `your-package-manager-run-here deploy` runs `next build` locally and ships the prebuilt `.next` output, then Harper serves it — no build runs on the cluster. (Building on the cluster currently fails; see the note in [`config.yaml`](./config.yaml).)
74
+
75
+ ### Deploy automatically from CI
76
+
77
+ The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) builds and deploys whenever you push a version tag:
78
+
79
+ ```sh
80
+ git tag v1.0.0
81
+ git push --tags
82
+ ```
83
+
84
+ Add these repository secrets first, under **Settings → Secrets and variables → Actions**:
85
+
86
+ - `HARPER_CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`)
87
+ - `HARPER_CLI_REFRESH_TOKEN` — a long-lived token CI authenticates with, so no password is stored
88
+
89
+ Set both in one command — this pipes the credentials straight from your cluster into GitHub, so the token never appears on screen or in your shell history:
90
+
91
+ ```sh
92
+ harper login --for-ci | gh secret set --env-file -
93
+ ```
94
+
95
+ (No [`gh` CLI](https://cli.github.com)? `harper login --for-ci | pbcopy` copies the two lines for you to paste in by hand.)
96
+
97
+ > **Why this template deploys differently.** The other create-harper templates deploy _by reference_: the cluster clones your repo at a pinned commit and builds there. Next.js can't do that yet — `.next` is gitignored, so a git reference carries no build output, and an on-cluster build currently fails ([nextjs#57](https://github.com/HarperFast/nextjs/issues/57), [nextjs#58](https://github.com/HarperFast/nextjs/issues/58)). Until those land, this template uploads the build itself.
74
98
 
75
99
  ## Keep Going!
76
100
 
@@ -0,0 +1,62 @@
1
+ # Deploys this app to your Harper cluster by *payload* via `harper deploy_component .`
2
+ # (`your-package-manager-run-here deploy`), which runs `next build` first and uploads the prebuilt
3
+ # `.next` output.
4
+ #
5
+ # The other create-harper templates deploy by *reference* (`harper deploy by_ref=true`), where the
6
+ # cluster clones your repo and builds on the node. Next.js can't use that yet: `.next` is gitignored
7
+ # (so a git reference carries no build output) and building on the cluster currently fails —
8
+ # Turbopack crashes inside a Harper worker thread (HarperFast/nextjs#57) and a webpack build
9
+ # overruns the component-load timeout (HarperFast/nextjs#58). Once those land, this template can
10
+ # switch to the by-reference workflow like the rest.
11
+ #
12
+ # Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually.
13
+ #
14
+ # Required repository secrets (Settings → Secrets and variables → Actions):
15
+ # HARPER_CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925
16
+ # HARPER_CLI_REFRESH_TOKEN a long-lived refresh token; the CLI mints a short-lived operation
17
+ # token from it on each run, so no password is stored in CI
18
+ #
19
+ # Set both in one command — this pipes them straight from your cluster into GitHub, so the token
20
+ # never appears on screen or in your shell history:
21
+ #
22
+ # harper login --for-ci | gh secret set --env-file -
23
+ name: Deploy to Harper Fabric
24
+ on:
25
+ workflow_dispatch:
26
+ push:
27
+ tags:
28
+ - 'v*'
29
+
30
+ concurrency:
31
+ group: deploy
32
+ cancel-in-progress: false
33
+
34
+ jobs:
35
+ deploy:
36
+ runs-on: ubuntu-latest
37
+ steps:
38
+ - name: Checkout code
39
+ uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
40
+ with:
41
+ fetch-depth: 0
42
+ fetch-tags: true
43
+ # your-package-manager-setup-step-here
44
+ - name: Set up Node.js
45
+ uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
46
+ with:
47
+ # your-package-manager-node-cache-here
48
+ node-version-file: '.nvmrc'
49
+ - name: Install dependencies
50
+ run: your-package-manager-install-here
51
+ - name: Run lint
52
+ run: your-package-manager-run-here lint
53
+ - name: Install Harper CLI
54
+ # Installed with npm regardless of this project's package manager: it is a global tool, and
55
+ # npm always comes with the Node.js set up above. Pinned to the 5.2 line; ^5.2.0 blocks a
56
+ # breaking 6.x bump.
57
+ run: npm install -g harper@^5.2.0
58
+ - name: Build & deploy
59
+ run: your-package-manager-run-here deploy
60
+ env:
61
+ HARPER_CLI_TARGET: ${{ secrets.HARPER_CLI_TARGET }}
62
+ HARPER_CLI_REFRESH_TOKEN: ${{ secrets.HARPER_CLI_REFRESH_TOKEN }}
@@ -17,7 +17,7 @@ npm install -g harper
17
17
  Then you can start your app:
18
18
 
19
19
  ```sh
20
- npm run dev
20
+ your-package-manager-run-here dev
21
21
  ```
22
22
 
23
23
  ### Define Your Schema
@@ -103,20 +103,62 @@ Take a look at the [default configuration](./config.yaml), which specifies how f
103
103
 
104
104
  ## Deployment
105
105
 
106
- When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster.
106
+ Deploy your app to a Harper cluster **by reference**: instead of uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit.
107
107
 
108
- Come back and log in your local CLI to your cluster:
108
+ First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it:
109
109
 
110
110
  ```sh
111
111
  harper login
112
112
  ```
113
113
 
114
- Then you can deploy your app to your cluster:
114
+ ### One-time setup (private repos)
115
+
116
+ So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted:
117
+
118
+ ```sh
119
+ your-package-manager-run-here deploy:setup
120
+ ```
121
+
122
+ This fetches your cluster's public key, has you provide a GitHub token (a fine-grained PAT with **Contents: Read-only**, or your `gh` CLI session), **encrypts it locally**, and stores only the ciphertext in the cluster's secret store. The plaintext never leaves your machine; the cluster decrypts it in memory only while cloning. Because the token is durable, rollbacks keep working for as long as it's valid.
123
+
124
+ > Public repo? Skip this step and drop `credential=true` from the `deploy` script — no credential is needed.
125
+
126
+ ### Deploy
115
127
 
116
128
  ```sh
117
- npm run deploy
129
+ your-package-manager-run-here deploy
118
130
  ```
119
131
 
132
+ This deploys the current commit over `git+https` — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again.
133
+
134
+ ### Deploy automatically from CI
135
+
136
+ The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag:
137
+
138
+ ```sh
139
+ git tag v1.0.0
140
+ git push --tags
141
+ ```
142
+
143
+ Add these repository secrets first, under **Settings → Secrets and variables → Actions**:
144
+
145
+ - `HARPER_CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`)
146
+ - `HARPER_CLI_REFRESH_TOKEN` — a long-lived token CI authenticates with, so no password is stored
147
+
148
+ Set both in one command — this pipes the credentials straight from your cluster into GitHub, so the token never appears on screen or in your shell history:
149
+
150
+ ```sh
151
+ harper login --for-ci | gh secret set --env-file -
152
+ ```
153
+
154
+ (No [`gh` CLI](https://cli.github.com)? `harper login --for-ci | pbcopy` copies the two lines for you to paste in by hand.)
155
+
156
+ The clone credential already lives in the cluster from `your-package-manager-run-here deploy:setup`, so CI never handles a token itself.
157
+
158
+ ### Private npm dependencies
159
+
160
+ If your app depends on private npm packages, run `your-package-manager-run-here deploy:setup` again and choose the npm registry — the same sealed-token flow, stored as a separate credential.
161
+
120
162
  ## Keep Going!
121
163
 
122
164
  For more information about getting started with Harper and building applications, see our [getting started guide](https://docs.harperdb.io/docs).
@@ -0,0 +1,63 @@
1
+ # Deploys this app to your Harper cluster by *reference* via `harper deploy by_ref=true`
2
+ # (`your-package-manager-run-here deploy`).
3
+ #
4
+ # Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster
5
+ # fetches the tagged commit over git+https (pinned by its exact SHA, so peers can't diverge on a
6
+ # moved tag), authenticating a private clone with the encrypted token you sealed once via
7
+ # `your-package-manager-run-here deploy:setup`. The credential lives on the cluster, so this
8
+ # workflow handles no token.
9
+ #
10
+ # Required repository secrets (Settings → Secrets and variables → Actions):
11
+ # HARPER_CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925
12
+ # HARPER_CLI_REFRESH_TOKEN a long-lived refresh token; the CLI mints a short-lived operation
13
+ # token from it on each run, so no password is stored in CI
14
+ #
15
+ # Set both in one command — this pipes them straight from your cluster into GitHub, so the token
16
+ # never appears on screen or in your shell history:
17
+ #
18
+ # harper login --for-ci | gh secret set --env-file -
19
+ #
20
+ # Public repo? Drop `credential=true` from the `deploy` script — no cluster-side auth needed.
21
+ # See the "Deployment" section of the README for details.
22
+ name: Deploy to Harper Fabric
23
+ on:
24
+ workflow_dispatch:
25
+ push:
26
+ tags:
27
+ - 'v*'
28
+
29
+ concurrency:
30
+ group: deploy
31
+ cancel-in-progress: false
32
+
33
+ jobs:
34
+ deploy:
35
+ runs-on: ubuntu-latest
36
+ steps:
37
+ - name: Checkout code
38
+ uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
39
+ with:
40
+ fetch-depth: 0
41
+ fetch-tags: true
42
+ # your-package-manager-setup-step-here
43
+ - name: Set up Node.js
44
+ uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
45
+ with:
46
+ # your-package-manager-node-cache-here
47
+ node-version-file: '.nvmrc'
48
+ - name: Install dependencies
49
+ run: your-package-manager-install-here
50
+ - name: Run unit tests
51
+ run: your-package-manager-run-here test
52
+ - name: Run lint
53
+ run: your-package-manager-run-here lint
54
+ - name: Install Harper CLI
55
+ # Installed with npm regardless of this project's package manager: it is a global tool, and
56
+ # npm always comes with the Node.js set up above. Pinned to the 5.2 line (where
57
+ # deploy-by-reference lands); ^5.2.0 blocks a breaking 6.x bump.
58
+ run: npm install -g harper@^5.2.0
59
+ - name: Deploy
60
+ run: your-package-manager-run-here deploy
61
+ env:
62
+ HARPER_CLI_TARGET: ${{ secrets.HARPER_CLI_TARGET }}
63
+ HARPER_CLI_REFRESH_TOKEN: ${{ secrets.HARPER_CLI_REFRESH_TOKEN }}
@@ -13,7 +13,8 @@
13
13
  "test": "node --test test/*.test.js",
14
14
  "test:watch": "node --watch --test test/*.test.js",
15
15
  "build": "vite build",
16
- "deploy": "harper deploy_component . restart=true replicated=true"
16
+ "deploy": "harper deploy by_ref=true credential=true restart=true replicated=true",
17
+ "deploy:setup": "harper deploy setup=true"
17
18
  },
18
19
  "dependencies": {
19
20
  "@harperfast/schema-codegen": "^2.0.0",