create-harper 1.11.7 → 1.12.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.
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 +1 -1
  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
@@ -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
  TypeScript is supported at runtime in Node.js through [type stripping](https://nodejs.org/api/typescript.html#type-stripping). Full TypeScript language support can be enabled through integrating third party build steps to transpile your TypeScript into JavaScript.
@@ -111,20 +111,62 @@ Take a look at the [default configuration](./config.yaml), which specifies how f
111
111
 
112
112
  ## Deployment
113
113
 
114
- When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster.
114
+ 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.
115
115
 
116
- Come back and log in your local CLI to your cluster:
116
+ 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:
117
117
 
118
118
  ```sh
119
119
  harper login
120
120
  ```
121
121
 
122
- Then you can deploy your app to your cluster:
122
+ ### One-time setup (private repos)
123
+
124
+ So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted:
125
+
126
+ ```sh
127
+ your-package-manager-run-here deploy:setup
128
+ ```
129
+
130
+ 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.
131
+
132
+ > Public repo? Skip this step and drop `credential=true` from the `deploy` script — no credential is needed.
133
+
134
+ ### Deploy
123
135
 
124
136
  ```sh
125
- npm run deploy
137
+ your-package-manager-run-here deploy
126
138
  ```
127
139
 
140
+ 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.
141
+
142
+ ### Deploy automatically from CI
143
+
144
+ The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag:
145
+
146
+ ```sh
147
+ git tag v1.0.0
148
+ git push --tags
149
+ ```
150
+
151
+ Add these repository secrets first, under **Settings → Secrets and variables → Actions**:
152
+
153
+ - `HARPER_CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`)
154
+ - `HARPER_CLI_REFRESH_TOKEN` — a long-lived token CI authenticates with, so no password is stored
155
+
156
+ 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:
157
+
158
+ ```sh
159
+ harper login --for-ci | gh secret set --env-file -
160
+ ```
161
+
162
+ (No [`gh` CLI](https://cli.github.com)? `harper login --for-ci | pbcopy` copies the two lines for you to paste in by hand.)
163
+
164
+ The clone credential already lives in the cluster from `your-package-manager-run-here deploy:setup`, so CI never handles a token itself.
165
+
166
+ ### Private npm dependencies
167
+
168
+ 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.
169
+
128
170
  ## Keep Going!
129
171
 
130
172
  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 }}
@@ -12,7 +12,8 @@
12
12
  "format": "prettier --write .",
13
13
  "test": "node --test test/*.test.js",
14
14
  "test:watch": "node --watch --test test/*.test.js",
15
- "deploy": "harper deploy_component . restart=true replicated=true"
15
+ "deploy": "harper deploy by_ref=true credential=true restart=true replicated=true",
16
+ "deploy:setup": "harper deploy setup=true"
16
17
  },
17
18
  "devDependencies": {
18
19
  "@eslint/js": "^10.0.1",
@@ -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",
@@ -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",
@@ -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
  TypeScript is supported at runtime in Node.js through [type stripping](https://nodejs.org/api/typescript.html#type-stripping). Full TypeScript language support can be enabled through integrating third party build steps to transpile your TypeScript into JavaScript.
@@ -111,20 +111,62 @@ Take a look at the [default configuration](./config.yaml), which specifies how f
111
111
 
112
112
  ## Deployment
113
113
 
114
- When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster.
114
+ 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.
115
115
 
116
- Come back and log in your local CLI to your cluster:
116
+ 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:
117
117
 
118
118
  ```sh
119
119
  harper login
120
120
  ```
121
121
 
122
- Then you can deploy your app to your cluster:
122
+ ### One-time setup (private repos)
123
+
124
+ So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted:
125
+
126
+ ```sh
127
+ your-package-manager-run-here deploy:setup
128
+ ```
129
+
130
+ 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.
131
+
132
+ > Public repo? Skip this step and drop `credential=true` from the `deploy` script — no credential is needed.
133
+
134
+ ### Deploy
123
135
 
124
136
  ```sh
125
- npm run deploy
137
+ your-package-manager-run-here deploy
126
138
  ```
127
139
 
140
+ 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.
141
+
142
+ ### Deploy automatically from CI
143
+
144
+ The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag:
145
+
146
+ ```sh
147
+ git tag v1.0.0
148
+ git push --tags
149
+ ```
150
+
151
+ Add these repository secrets first, under **Settings → Secrets and variables → Actions**:
152
+
153
+ - `HARPER_CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`)
154
+ - `HARPER_CLI_REFRESH_TOKEN` — a long-lived token CI authenticates with, so no password is stored
155
+
156
+ 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:
157
+
158
+ ```sh
159
+ harper login --for-ci | gh secret set --env-file -
160
+ ```
161
+
162
+ (No [`gh` CLI](https://cli.github.com)? `harper login --for-ci | pbcopy` copies the two lines for you to paste in by hand.)
163
+
164
+ The clone credential already lives in the cluster from `your-package-manager-run-here deploy:setup`, so CI never handles a token itself.
165
+
166
+ ### Private npm dependencies
167
+
168
+ 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.
169
+
128
170
  ## Keep Going!
129
171
 
130
172
  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.ts",
14
14
  "test:watch": "node --watch --test test/*.test.ts",
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",