create-harper 1.10.15 → 1.11.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 (44) hide show
  1. package/README.md +2 -0
  2. package/lib/constants/frameworks.js +2 -0
  3. package/lib/constants/templates.d.ts +18 -2
  4. package/lib/constants/templates.js +38 -1
  5. package/package.json +4 -2
  6. package/template-nextjs/README.md +79 -0
  7. package/template-nextjs/_aiignore +1 -0
  8. package/template-nextjs/_claude/launch.json +11 -0
  9. package/template-nextjs/_env +1 -0
  10. package/template-nextjs/_env.example +1 -0
  11. package/template-nextjs/_github/workflow/deploy.yaml +31 -0
  12. package/template-nextjs/_gitignore +34 -0
  13. package/template-nextjs/_nvmrc +1 -0
  14. package/template-nextjs/app/actions.js +26 -0
  15. package/template-nextjs/app/layout.js +14 -0
  16. package/template-nextjs/app/page.js +55 -0
  17. package/template-nextjs/config.yaml +28 -0
  18. package/template-nextjs/eslint.config.mjs +19 -0
  19. package/template-nextjs/graphql.config.yml +3 -0
  20. package/template-nextjs/jsconfig.json +7 -0
  21. package/template-nextjs/next.config.mjs +6 -0
  22. package/template-nextjs/package.json +28 -0
  23. package/template-nextjs/pnpm-workspace.yaml +5 -0
  24. package/template-nextjs/schema.graphql +4 -0
  25. package/template-nextjs-ts/README.md +79 -0
  26. package/template-nextjs-ts/_aiignore +1 -0
  27. package/template-nextjs-ts/_claude/launch.json +11 -0
  28. package/template-nextjs-ts/_env +1 -0
  29. package/template-nextjs-ts/_env.example +1 -0
  30. package/template-nextjs-ts/_github/workflow/deploy.yaml +31 -0
  31. package/template-nextjs-ts/_gitignore +34 -0
  32. package/template-nextjs-ts/_nvmrc +1 -0
  33. package/template-nextjs-ts/app/actions.ts +25 -0
  34. package/template-nextjs-ts/app/layout.tsx +16 -0
  35. package/template-nextjs-ts/app/page.tsx +55 -0
  36. package/template-nextjs-ts/config.yaml +28 -0
  37. package/template-nextjs-ts/eslint.config.mjs +19 -0
  38. package/template-nextjs-ts/graphql.config.yml +3 -0
  39. package/template-nextjs-ts/harper.d.ts +30 -0
  40. package/template-nextjs-ts/next.config.mjs +6 -0
  41. package/template-nextjs-ts/package.json +31 -0
  42. package/template-nextjs-ts/pnpm-workspace.yaml +5 -0
  43. package/template-nextjs-ts/schema.graphql +4 -0
  44. package/template-nextjs-ts/tsconfig.json +23 -0
package/README.md CHANGED
@@ -69,6 +69,8 @@ Currently supported template presets include:
69
69
  - `vanilla-ts`
70
70
  - `react`
71
71
  - `react-ts`
72
+ - `nextjs`
73
+ - `nextjs-ts`
72
74
 
73
75
  You can use `.` for the project name to scaffold in the current directory.
74
76
 
@@ -5,6 +5,7 @@ const {
5
5
  blue,
6
6
  cyan,
7
7
  green,
8
+ magenta,
8
9
  yellow,
9
10
  } = colors;
10
11
 
@@ -28,6 +29,7 @@ const frameworkMeta = {
28
29
  vanilla: { display: 'Vanilla', color: yellow },
29
30
  react: { display: 'React', color: cyan },
30
31
  vue: { display: 'Vue', color: green },
32
+ nextjs: { display: 'Next.js', color: magenta },
31
33
  };
32
34
 
33
35
  /**
@@ -1,4 +1,4 @@
1
- export type Framework = 'vanilla' | 'react' | 'vue';
1
+ export type Framework = 'vanilla' | 'react' | 'vue' | 'nextjs';
2
2
 
3
3
  export type TemplateName =
4
4
  | 'vanilla-ts'
@@ -10,7 +10,9 @@ export type TemplateName =
10
10
  | 'vue-ts'
11
11
  | 'vue'
12
12
  | 'vue-ts-ssr'
13
- | 'vue-ssr';
13
+ | 'vue-ssr'
14
+ | 'nextjs-ts'
15
+ | 'nextjs';
14
16
 
15
17
  export interface TemplateInfo {
16
18
  /** The canonical template name (e.g. 'vanilla', 'react-ts'). Used to scaffold. */
@@ -27,6 +29,11 @@ export interface TemplateInfo {
27
29
  typescript: boolean;
28
30
  /** Whether the template is server-side rendered. */
29
31
  ssr: boolean;
32
+ /**
33
+ * Whether a Studio template package is built and published for this template. Defaults to true;
34
+ * set to false for templates that don't (yet) run in the Studio's deploy-only model.
35
+ */
36
+ studio?: boolean;
30
37
  /** The published Studio template package for this template. */
31
38
  npmPackage: string;
32
39
  /** A link to the template's source on GitHub. */
@@ -51,4 +58,13 @@ export declare const templateNames: readonly [
51
58
  'vue',
52
59
  'vue-ts-ssr',
53
60
  'vue-ssr',
61
+ 'nextjs-ts',
62
+ 'nextjs',
54
63
  ];
64
+
65
+ /**
66
+ * The subset of {@link templateNames} for which a Studio template package is built and published
67
+ * (every template whose catalog entry does not set `studio: false`). Consumed by the Studio
68
+ * build/publish scripts.
69
+ */
70
+ export declare const studioTemplateNames: readonly TemplateName[];
@@ -1,7 +1,7 @@
1
1
  const CREATE_HARPER_TREE = 'https://github.com/HarperFast/create-harper/tree/main';
2
2
 
3
3
  /**
4
- * @typedef {'vanilla' | 'react' | 'vue'} Framework
4
+ * @typedef {'vanilla' | 'react' | 'vue' | 'nextjs'} Framework
5
5
  */
6
6
 
7
7
  /**
@@ -13,6 +13,9 @@ const CREATE_HARPER_TREE = 'https://github.com/HarperFast/create-harper/tree/mai
13
13
  * @property {string[]} tags - Tags describing the template's stack.
14
14
  * @property {boolean} typescript - Whether the template uses TypeScript.
15
15
  * @property {boolean} ssr - Whether the template is server-side rendered.
16
+ * @property {boolean} [studio] - Whether a Studio template package is built and published for this
17
+ * template. Defaults to true; set to false for templates that don't (yet) run in the Studio's
18
+ * deploy-only model. See {@link studioTemplateNames}.
16
19
  * @property {string} npmPackage - The published Studio template package for this template.
17
20
  * @property {string} githubUrl - A link to the template's source on GitHub.
18
21
  */
@@ -131,6 +134,31 @@ export const templates = [
131
134
  typescript: false,
132
135
  ssr: true,
133
136
  }),
137
+ template({
138
+ name: 'nextjs-ts',
139
+ framework: 'nextjs',
140
+ title: 'Next.js + TypeScript',
141
+ description: 'A type-safe Next.js app that reads and writes Harper tables directly from server actions.',
142
+ tags: ['Next.js', 'TypeScript', 'React', 'App Router'],
143
+ typescript: true,
144
+ // Next.js renders on the server (the app is force-dynamic and reads Harper per request), so
145
+ // this is SSR even though the name has no `-ssr` suffix (that suffix marks the Vite variants).
146
+ ssr: true,
147
+ // Not built/published as a Studio template: the plugin needs a prebuilt deploy (its on-startup
148
+ // build races on multi-thread clusters — HarperFast/nextjs#52) and Studio's edit-in-place
149
+ // model doesn't rebuild, so it isn't a fit today.
150
+ studio: false,
151
+ }),
152
+ template({
153
+ name: 'nextjs',
154
+ framework: 'nextjs',
155
+ title: 'Next.js',
156
+ description: "A Next.js app wired to Harper's Resource API, reading and writing tables from server actions.",
157
+ tags: ['Next.js', 'React', 'App Router'],
158
+ typescript: false,
159
+ ssr: true,
160
+ studio: false,
161
+ }),
134
162
  ];
135
163
 
136
164
  /**
@@ -140,3 +168,12 @@ export const templates = [
140
168
  * @type {string[]}
141
169
  */
142
170
  export const templateNames = templates.map((t) => t.name);
171
+
172
+ /**
173
+ * The subset of {@link templateNames} for which a Studio template package is built and published
174
+ * (i.e. every template except those with `studio: false`). The Studio build/publish scripts iterate
175
+ * this instead of {@link templateNames} so opt-out templates are skipped.
176
+ *
177
+ * @type {string[]}
178
+ */
179
+ export const studioTemplateNames = templates.filter((t) => t.studio !== false).map((t) => t.name);
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.10.15",
4
+ "version": "1.11.1",
5
5
  "type": "module",
6
6
  "sideEffects": false,
7
7
  "exports": {
@@ -31,7 +31,9 @@
31
31
  "template-vue/",
32
32
  "template-vue-ts/",
33
33
  "template-vue-ssr/",
34
- "template-vue-ts-ssr/"
34
+ "template-vue-ts-ssr/",
35
+ "template-nextjs/",
36
+ "template-nextjs-ts/"
35
37
  ],
36
38
  "scripts": {
37
39
  "commitlint": "commitlint --edit",
@@ -0,0 +1,79 @@
1
+ # your-project-name-here
2
+
3
+ A [Next.js](https://nextjs.org) app running on Harper via [`@harperfast/nextjs`](https://github.com/HarperFast/nextjs). Your new app is now ready for development!
4
+
5
+ Because the app runs _inside_ Harper, server-side code (server actions and server components) reads and writes your database directly through the injected `tables` global — no separate API server and no network round-trip.
6
+
7
+ The starter ships one tiny end-to-end example: a counter stored in a Harper table, read by a server component and incremented by a server action.
8
+
9
+ ## Installation
10
+
11
+ Make sure you have [installed Harper](https://docs.harperdb.io/docs/deployments/install-harper):
12
+
13
+ ```sh
14
+ npm install -g harper
15
+ ```
16
+
17
+ ## Development
18
+
19
+ Start the app:
20
+
21
+ ```sh
22
+ npm run dev
23
+ ```
24
+
25
+ Then open [http://localhost:9926](http://localhost:9926) 🎉
26
+
27
+ Click the button — the count persists in Harper across reloads and restarts.
28
+
29
+ ### Define Your Schema
30
+
31
+ Your tables live in [`schema.graphql`](./schema.graphql). The starter defines a single `Count` table; add your own `@table` types there and they become available on the `tables` global.
32
+
33
+ ### Access Harper From Server Code
34
+
35
+ Harper injects `tables` and `transaction` globals into server-side code, so server actions and server components read and write your database directly — no import needed. Use an atomic `addTo` inside a `transaction` for writes that stay correct when requests overlap across worker threads and replicated nodes (a read-then-write would lose concurrent increments):
36
+
37
+ ```js
38
+ 'use server';
39
+
40
+ export async function getCount() {
41
+ const record = await tables.Count.get('count');
42
+ return record?.value ?? 0;
43
+ }
44
+
45
+ export async function increment() {
46
+ await transaction(async () => {
47
+ const record = await tables.Count.update('count');
48
+ record.addTo('value', 1);
49
+ });
50
+ }
51
+ ```
52
+
53
+ > **Don't** add a top-level `import 'harper'` in these modules. It runs during the Next.js production build (when Next collects page data) and conflicts with the running database — use the injected globals instead.
54
+
55
+ Put data access in **server actions** (see [`app/actions.js`](./app/actions.js)) so that both server _and_ client components can share the same functions. Any action a client can reach is a public endpoint, so add your own authorization checks before shipping mutations that matter.
56
+
57
+ ## Deployment
58
+
59
+ When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster.
60
+
61
+ Come back and log your local CLI into your cluster:
62
+
63
+ ```sh
64
+ harper login
65
+ ```
66
+
67
+ Then deploy your app:
68
+
69
+ ```sh
70
+ npm run deploy
71
+ ```
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).)
74
+
75
+ ## Keep Going!
76
+
77
+ For more on building Harper applications, see the [getting started guide](https://docs.harperdb.io/docs).
78
+
79
+ For more on Harper Components, see the [Components documentation](https://docs.harperdb.io/docs/reference/components).
@@ -0,0 +1 @@
1
+ .env
@@ -0,0 +1,11 @@
1
+ {
2
+ "version": "0.0.1",
3
+ "configurations": [
4
+ {
5
+ "name": "harper",
6
+ "runtimeExecutable": "your-package-manager-here",
7
+ "runtimeArgs": ["run", "dev"],
8
+ "port": 9926
9
+ }
10
+ ]
11
+ }
@@ -0,0 +1 @@
1
+ CLI_TARGET='your-fabric.harper.fast-cluster-url-here'
@@ -0,0 +1 @@
1
+ CLI_TARGET='YOUR_FABRIC.HARPER.FAST_CLUSTER_URL_HERE'
@@ -0,0 +1,31 @@
1
+ name: Deploy to Harper Fabric
2
+ on:
3
+ workflow_dispatch:
4
+ # push:
5
+ # branches:
6
+ # - main
7
+
8
+ concurrency:
9
+ group: main
10
+ cancel-in-progress: false
11
+
12
+ jobs:
13
+ deploy:
14
+ runs-on: ubuntu-latest
15
+ steps:
16
+ - name: Checkout code
17
+ uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
18
+ with:
19
+ fetch-depth: 0
20
+ fetch-tags: true
21
+ - name: Set up Node.js
22
+ uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
23
+ with:
24
+ cache: 'npm'
25
+ node-version-file: '.nvmrc'
26
+ - name: Install dependencies
27
+ run: npm ci
28
+ - name: Run lint
29
+ run: npm run lint
30
+ - name: Build & deploy
31
+ run: npm run deploy
@@ -0,0 +1,34 @@
1
+ .DS_Store
2
+
3
+ # dependencies
4
+ node_modules/
5
+ .pnp
6
+ .pnp.*
7
+
8
+ # next.js
9
+ /.next/
10
+ /out/
11
+ /build
12
+
13
+ # debug logs
14
+ logs
15
+ *.log
16
+ npm-debug.log*
17
+ yarn-debug.log*
18
+ yarn-error.log*
19
+
20
+ # testing
21
+ /coverage
22
+
23
+ # typescript
24
+ *.tsbuildinfo
25
+ next-env.d.ts
26
+
27
+ # dotenv environment variable files
28
+ .env
29
+ .env.*
30
+ !.env.example
31
+
32
+ # misc
33
+ *.pem
34
+ .vercel
@@ -0,0 +1 @@
1
+ 24.13.1
@@ -0,0 +1,26 @@
1
+ 'use server';
2
+
3
+ /* global tables, transaction */
4
+ import { revalidatePath } from 'next/cache';
5
+
6
+ // Server actions run *inside* Harper, so they read and write tables directly through the injected
7
+ // globals — no separate API and no network round-trip. Harper provides `tables` and `transaction`,
8
+ // so use them directly; do NOT add a top-level `import 'harper'` — that import runs during the
9
+ // Next.js production build and conflicts with the running database.
10
+
11
+ // The whole counter lives in a single row keyed 'count', so reads are a cheap point lookup.
12
+ export async function getCount() {
13
+ const record = await tables.Count.get('count');
14
+ return record?.value ?? 0;
15
+ }
16
+
17
+ export async function increment() {
18
+ // Atomic increment: `addTo` inside a transaction is safe when requests overlap across worker
19
+ // threads and replicated nodes — a read-then-write would lose concurrent increments. The
20
+ // transaction also creates the row on first use.
21
+ await transaction(async () => {
22
+ const record = await tables.Count.update('count');
23
+ record.addTo('value', 1);
24
+ });
25
+ revalidatePath('/');
26
+ }
@@ -0,0 +1,14 @@
1
+ export const metadata = {
2
+ title: 'Next.js on Harper',
3
+ description: 'A Next.js app powered by Harper',
4
+ };
5
+
6
+ export default function RootLayout({ children }) {
7
+ return (
8
+ <html lang="en">
9
+ <body style={{ margin: 0, fontFamily: 'system-ui, -apple-system, sans-serif', color: '#1e293b' }}>
10
+ {children}
11
+ </body>
12
+ </html>
13
+ );
14
+ }
@@ -0,0 +1,55 @@
1
+ import { getCount, increment } from './actions';
2
+
3
+ // Read the count fresh on every request rather than caching it at build time.
4
+ export const dynamic = 'force-dynamic';
5
+
6
+ export default async function Page() {
7
+ const count = await getCount();
8
+
9
+ return (
10
+ <main
11
+ style={{
12
+ minHeight: '100vh',
13
+ display: 'flex',
14
+ flexDirection: 'column',
15
+ justifyContent: 'center',
16
+ alignItems: 'center',
17
+ gap: '1rem',
18
+ padding: '2rem',
19
+ textAlign: 'center',
20
+ }}
21
+ >
22
+ <h1 style={{ margin: 0 }}>Next.js + Harper</h1>
23
+ <p style={{ margin: 0, color: '#64748b', maxWidth: '32rem' }}>
24
+ This counter is stored in a Harper table. Clicking the button calls a{' '}
25
+ <a href="https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations">
26
+ server action
27
+ </a>{' '}
28
+ that reads and writes the table directly — no separate API.
29
+ </p>
30
+ {
31
+ /* A plain form calling a server action: no client component needed, and the browser
32
+ shows its own pending state while the action runs. */
33
+ }
34
+ <form action={increment}>
35
+ <button
36
+ type="submit"
37
+ style={{
38
+ fontSize: '1.125rem',
39
+ padding: '0.75rem 1.5rem',
40
+ borderRadius: '8px',
41
+ border: '1px solid #cbd5e1',
42
+ background: '#403b8a',
43
+ color: 'white',
44
+ cursor: 'pointer',
45
+ }}
46
+ >
47
+ count is {count}
48
+ </button>
49
+ </form>
50
+ <p style={{ margin: 0, color: '#94a3b8', fontSize: '0.875rem' }}>
51
+ Edit the schema in <code>schema.graphql</code> and the logic in <code>app/actions.js</code>.
52
+ </p>
53
+ </main>
54
+ );
55
+ }
@@ -0,0 +1,28 @@
1
+ # yaml-language-server: $schema=./node_modules/harper/config-app.schema.json
2
+
3
+ # This is the configuration file for the application.
4
+ # It specifies built-in Harper components that will load the specified feature and files.
5
+ # For more information, see https://docs.harperdb.io/docs/reference/components/built-in-extensions
6
+
7
+ # Load Environment Variables from the specified file
8
+ # loadEnv:
9
+ # files: '.env'
10
+
11
+ # Reads GraphQL schemas to define the schema of database/tables/attributes.
12
+ graphqlSchema:
13
+ files: 'schema.graphql'
14
+
15
+ # Runs the Next.js app as a Harper component. The npm scripts run `next build` first, then this
16
+ # component serves the prebuilt `.next` output (`prebuilt: true` below); `harper dev` builds once
17
+ # and then serves with hot-module reloading. Server-side code (server actions and server components)
18
+ # reads and writes Harper tables directly through the injected `tables` and `transaction` globals —
19
+ # see app/actions.js. Because this plugin owns HTTP routing for the app, there is no `static` or
20
+ # `rest` handler here.
21
+ '@harperfast/nextjs':
22
+ package: '@harperfast/nextjs'
23
+ # Serve a prebuilt `.next` (the npm scripts run `next build` for you) instead of building on
24
+ # startup. Building on a Harper cluster currently fails — the Turbopack build crashes inside a
25
+ # worker thread, and a webpack build overruns the component-load timeout — so the app never
26
+ # serves. Prebuilding locally sidesteps both. See
27
+ # https://github.com/HarperFast/nextjs/issues/57 and https://github.com/HarperFast/nextjs/issues/58
28
+ prebuilt: true
@@ -0,0 +1,19 @@
1
+ import next from 'eslint-config-next';
2
+
3
+ const eslintConfig = [
4
+ ...next,
5
+ {
6
+ // `tables` and `transaction` are globals injected by the Harper runtime for server-side code.
7
+ languageOptions: {
8
+ globals: {
9
+ tables: 'readonly',
10
+ transaction: 'readonly',
11
+ },
12
+ },
13
+ },
14
+ {
15
+ ignores: ['.next/', 'node_modules/'],
16
+ },
17
+ ];
18
+
19
+ export default eslintConfig;
@@ -0,0 +1,3 @@
1
+ schema: schema.graphql
2
+ include: node_modules/harper/schema.graphql
3
+ documents: '**/*.graphql'
@@ -0,0 +1,7 @@
1
+ {
2
+ "compilerOptions": {
3
+ "paths": {
4
+ "@/*": ["./*"]
5
+ }
6
+ }
7
+ }
@@ -0,0 +1,6 @@
1
+ import { withHarper } from '@harperfast/nextjs';
2
+
3
+ // `withHarper` wires this Next.js app into Harper: it marks the `harper` package as a server
4
+ // external so `import 'harper'` resolves to the running Harper runtime (rather than being bundled),
5
+ // giving server-side code access to the `tables` global. Add your own Next.js config inside.
6
+ export default withHarper({});
@@ -0,0 +1,28 @@
1
+ {
2
+ "name": "your-package-name-here",
3
+ "version": "0.0.0",
4
+ "private": true,
5
+ "repository": "github:HarperFast/create-harper",
6
+ "scripts": {
7
+ "agent:run": "npx -y @harperfast/agent@latest",
8
+ "agent:skills:update": "npx -y skills@latest add harperfast/skills --all --yes",
9
+ "start": "next build && harper run .",
10
+ "dev": "next build && harper dev .",
11
+ "build": "next build",
12
+ "lint": "eslint .",
13
+ "format": "prettier --write .",
14
+ "deploy": "next build && harper deploy_component . restart=true replicated=true"
15
+ },
16
+ "dependencies": {
17
+ "@harperfast/nextjs": "^2.2.3",
18
+ "next": "^16.2.11",
19
+ "react": "^19.2.8",
20
+ "react-dom": "^19.2.8"
21
+ },
22
+ "devDependencies": {
23
+ "eslint": "^9.27.0",
24
+ "eslint-config-next": "^16.2.11",
25
+ "prettier": "^3.8.1",
26
+ "typescript": "^5.9.3"
27
+ }
28
+ }
@@ -0,0 +1,5 @@
1
+ # Pre-approve the build scripts for Next.js's native dependencies so `pnpm install` doesn't halt
2
+ # on them (pnpm 10.12+/11 gate dependency build scripts by default). npm and yarn ignore this file.
3
+ allowBuilds:
4
+ sharp: true
5
+ unrs-resolver: true
@@ -0,0 +1,4 @@
1
+ type Count @table @export {
2
+ id: ID @primaryKey
3
+ value: Int
4
+ }
@@ -0,0 +1,79 @@
1
+ # your-project-name-here
2
+
3
+ A type-safe [Next.js](https://nextjs.org) app running on Harper via [`@harperfast/nextjs`](https://github.com/HarperFast/nextjs). Your new app is now ready for development!
4
+
5
+ Because the app runs _inside_ Harper, server-side code (server actions and server components) reads and writes your database directly through the injected `tables` global — no separate API server and no network round-trip.
6
+
7
+ The starter ships one tiny end-to-end example: a counter stored in a Harper table, read by a server component and incremented by a server action.
8
+
9
+ ## Installation
10
+
11
+ Make sure you have [installed Harper](https://docs.harperdb.io/docs/deployments/install-harper):
12
+
13
+ ```sh
14
+ npm install -g harper
15
+ ```
16
+
17
+ ## Development
18
+
19
+ Start the app:
20
+
21
+ ```sh
22
+ npm run dev
23
+ ```
24
+
25
+ Then open [http://localhost:9926](http://localhost:9926) 🎉
26
+
27
+ Click the button — the count persists in Harper across reloads and restarts.
28
+
29
+ ### Define Your Schema
30
+
31
+ Your tables live in [`schema.graphql`](./schema.graphql). The starter defines a single `Count` table; add your own `@table` types there, then mirror their shape in [`harper.d.ts`](./harper.d.ts) so your server code stays type-safe. (The `@harperfast/schema-codegen` component can also generate these types for you.)
32
+
33
+ ### Access Harper From Server Code
34
+
35
+ Harper injects `tables` and `transaction` globals into server-side code, so server actions and server components read and write your database directly — no import needed (their types come from [`harper.d.ts`](./harper.d.ts)). Use an atomic `addTo` inside a `transaction` for writes that stay correct when requests overlap across worker threads and replicated nodes (a read-then-write would lose concurrent increments):
36
+
37
+ ```ts
38
+ 'use server';
39
+
40
+ export async function getCount(): Promise<number> {
41
+ const record = await tables.Count.get('count');
42
+ return record?.value ?? 0;
43
+ }
44
+
45
+ export async function increment(): Promise<void> {
46
+ await transaction(async () => {
47
+ const record = await tables.Count.update('count');
48
+ record.addTo('value', 1);
49
+ });
50
+ }
51
+ ```
52
+
53
+ > **Don't** add a top-level `import 'harper'` in these modules. It runs during the Next.js production build (when Next collects page data) and conflicts with the running database — use the injected globals instead.
54
+
55
+ Put data access in **server actions** (see [`app/actions.ts`](./app/actions.ts)) so that both server _and_ client components can share the same functions. Any action a client can reach is a public endpoint, so add your own authorization checks before shipping mutations that matter.
56
+
57
+ ## Deployment
58
+
59
+ When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster.
60
+
61
+ Come back and log your local CLI into your cluster:
62
+
63
+ ```sh
64
+ harper login
65
+ ```
66
+
67
+ Then deploy your app:
68
+
69
+ ```sh
70
+ npm run deploy
71
+ ```
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).)
74
+
75
+ ## Keep Going!
76
+
77
+ For more on building Harper applications, see the [getting started guide](https://docs.harperdb.io/docs).
78
+
79
+ For more on Harper Components, see the [Components documentation](https://docs.harperdb.io/docs/reference/components).
@@ -0,0 +1 @@
1
+ .env
@@ -0,0 +1,11 @@
1
+ {
2
+ "version": "0.0.1",
3
+ "configurations": [
4
+ {
5
+ "name": "harper",
6
+ "runtimeExecutable": "your-package-manager-here",
7
+ "runtimeArgs": ["run", "dev"],
8
+ "port": 9926
9
+ }
10
+ ]
11
+ }
@@ -0,0 +1 @@
1
+ CLI_TARGET='your-fabric.harper.fast-cluster-url-here'
@@ -0,0 +1 @@
1
+ CLI_TARGET='YOUR_FABRIC.HARPER.FAST_CLUSTER_URL_HERE'
@@ -0,0 +1,31 @@
1
+ name: Deploy to Harper Fabric
2
+ on:
3
+ workflow_dispatch:
4
+ # push:
5
+ # branches:
6
+ # - main
7
+
8
+ concurrency:
9
+ group: main
10
+ cancel-in-progress: false
11
+
12
+ jobs:
13
+ deploy:
14
+ runs-on: ubuntu-latest
15
+ steps:
16
+ - name: Checkout code
17
+ uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
18
+ with:
19
+ fetch-depth: 0
20
+ fetch-tags: true
21
+ - name: Set up Node.js
22
+ uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
23
+ with:
24
+ cache: 'npm'
25
+ node-version-file: '.nvmrc'
26
+ - name: Install dependencies
27
+ run: npm ci
28
+ - name: Run lint
29
+ run: npm run lint
30
+ - name: Build & deploy
31
+ run: npm run deploy
@@ -0,0 +1,34 @@
1
+ .DS_Store
2
+
3
+ # dependencies
4
+ node_modules/
5
+ .pnp
6
+ .pnp.*
7
+
8
+ # next.js
9
+ /.next/
10
+ /out/
11
+ /build
12
+
13
+ # debug logs
14
+ logs
15
+ *.log
16
+ npm-debug.log*
17
+ yarn-debug.log*
18
+ yarn-error.log*
19
+
20
+ # testing
21
+ /coverage
22
+
23
+ # typescript
24
+ *.tsbuildinfo
25
+ next-env.d.ts
26
+
27
+ # dotenv environment variable files
28
+ .env
29
+ .env.*
30
+ !.env.example
31
+
32
+ # misc
33
+ *.pem
34
+ .vercel
@@ -0,0 +1 @@
1
+ 24.13.1
@@ -0,0 +1,25 @@
1
+ 'use server';
2
+
3
+ import { revalidatePath } from 'next/cache';
4
+
5
+ // Server actions run *inside* Harper, so they read and write tables directly through the injected
6
+ // globals — no separate API and no network round-trip. Harper provides `tables` and `transaction`,
7
+ // so use them directly; do NOT add a top-level `import 'harper'` — that import runs during the
8
+ // Next.js production build and conflicts with the running database.
9
+
10
+ // The whole counter lives in a single row keyed 'count', so reads are a cheap point lookup.
11
+ export async function getCount(): Promise<number> {
12
+ const record = await tables.Count.get('count');
13
+ return record?.value ?? 0;
14
+ }
15
+
16
+ export async function increment(): Promise<void> {
17
+ // Atomic increment: `addTo` inside a transaction is safe when requests overlap across worker
18
+ // threads and replicated nodes — a read-then-write would lose concurrent increments. The
19
+ // transaction also creates the row on first use.
20
+ await transaction(async () => {
21
+ const record = await tables.Count.update('count');
22
+ record.addTo('value', 1);
23
+ });
24
+ revalidatePath('/');
25
+ }
@@ -0,0 +1,16 @@
1
+ import type { ReactNode } from 'react';
2
+
3
+ export const metadata = {
4
+ title: 'Next.js on Harper',
5
+ description: 'A Next.js app powered by Harper',
6
+ };
7
+
8
+ export default function RootLayout({ children }: { children: ReactNode }) {
9
+ return (
10
+ <html lang="en">
11
+ <body style={{ margin: 0, fontFamily: 'system-ui, -apple-system, sans-serif', color: '#1e293b' }}>
12
+ {children}
13
+ </body>
14
+ </html>
15
+ );
16
+ }
@@ -0,0 +1,55 @@
1
+ import { getCount, increment } from './actions';
2
+
3
+ // Read the count fresh on every request rather than caching it at build time.
4
+ export const dynamic = 'force-dynamic';
5
+
6
+ export default async function Page() {
7
+ const count = await getCount();
8
+
9
+ return (
10
+ <main
11
+ style={{
12
+ minHeight: '100vh',
13
+ display: 'flex',
14
+ flexDirection: 'column',
15
+ justifyContent: 'center',
16
+ alignItems: 'center',
17
+ gap: '1rem',
18
+ padding: '2rem',
19
+ textAlign: 'center',
20
+ }}
21
+ >
22
+ <h1 style={{ margin: 0 }}>Next.js + Harper</h1>
23
+ <p style={{ margin: 0, color: '#64748b', maxWidth: '32rem' }}>
24
+ This counter is stored in a Harper table. Clicking the button calls a{' '}
25
+ <a href="https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations">
26
+ server action
27
+ </a>{' '}
28
+ that reads and writes the table directly — no separate API.
29
+ </p>
30
+ {
31
+ /* A plain form calling a server action: no client component needed, and the browser
32
+ shows its own pending state while the action runs. */
33
+ }
34
+ <form action={increment}>
35
+ <button
36
+ type="submit"
37
+ style={{
38
+ fontSize: '1.125rem',
39
+ padding: '0.75rem 1.5rem',
40
+ borderRadius: '8px',
41
+ border: '1px solid #cbd5e1',
42
+ background: '#403b8a',
43
+ color: 'white',
44
+ cursor: 'pointer',
45
+ }}
46
+ >
47
+ count is {count}
48
+ </button>
49
+ </form>
50
+ <p style={{ margin: 0, color: '#94a3b8', fontSize: '0.875rem' }}>
51
+ Edit the schema in <code>schema.graphql</code> and the logic in <code>app/actions.ts</code>.
52
+ </p>
53
+ </main>
54
+ );
55
+ }
@@ -0,0 +1,28 @@
1
+ # yaml-language-server: $schema=./node_modules/harper/config-app.schema.json
2
+
3
+ # This is the configuration file for the application.
4
+ # It specifies built-in Harper components that will load the specified feature and files.
5
+ # For more information, see https://docs.harperdb.io/docs/reference/components/built-in-extensions
6
+
7
+ # Load Environment Variables from the specified file
8
+ # loadEnv:
9
+ # files: '.env'
10
+
11
+ # Reads GraphQL schemas to define the schema of database/tables/attributes.
12
+ graphqlSchema:
13
+ files: 'schema.graphql'
14
+
15
+ # Runs the Next.js app as a Harper component. The npm scripts run `next build` first, then this
16
+ # component serves the prebuilt `.next` output (`prebuilt: true` below); `harper dev` builds once
17
+ # and then serves with hot-module reloading. Server-side code (server actions and server components)
18
+ # reads and writes Harper tables directly through the injected `tables` and `transaction` globals —
19
+ # see app/actions.ts. Because this plugin owns HTTP routing for the app, there is no `static` or
20
+ # `rest` handler here.
21
+ '@harperfast/nextjs':
22
+ package: '@harperfast/nextjs'
23
+ # Serve a prebuilt `.next` (the npm scripts run `next build` for you) instead of building on
24
+ # startup. Building on a Harper cluster currently fails — the Turbopack build crashes inside a
25
+ # worker thread, and a webpack build overruns the component-load timeout — so the app never
26
+ # serves. Prebuilding locally sidesteps both. See
27
+ # https://github.com/HarperFast/nextjs/issues/57 and https://github.com/HarperFast/nextjs/issues/58
28
+ prebuilt: true
@@ -0,0 +1,19 @@
1
+ import next from 'eslint-config-next';
2
+
3
+ const eslintConfig = [
4
+ ...next,
5
+ {
6
+ // `tables` and `transaction` are globals injected by the Harper runtime for server-side code.
7
+ languageOptions: {
8
+ globals: {
9
+ tables: 'readonly',
10
+ transaction: 'readonly',
11
+ },
12
+ },
13
+ },
14
+ {
15
+ ignores: ['.next/', 'node_modules/'],
16
+ },
17
+ ];
18
+
19
+ export default eslintConfig;
@@ -0,0 +1,3 @@
1
+ schema: schema.graphql
2
+ include: node_modules/harper/schema.graphql
3
+ documents: '**/*.graphql'
@@ -0,0 +1,30 @@
1
+ // Ambient type declarations for the Harper runtime.
2
+ //
3
+ // Harper injects globals into server-side code: `tables` (one entry per `@table` in schema.graphql)
4
+ // and `transaction` (runs a callback in a committing transaction). These hand-written declarations
5
+ // give you type-safe access. As you add tables and columns, mirror them here. (The
6
+ // `@harperfast/schema-codegen` component can also generate the table types for you.)
7
+
8
+ export interface CountRecord {
9
+ id: string;
10
+ value: number;
11
+ }
12
+
13
+ /** An updatable record from `tables.<Table>.update(id)`, mutated inside a `transaction(...)`. */
14
+ interface UpdatableRecord<T> {
15
+ addTo(property: keyof T, value: number): void;
16
+ subtractFrom(property: keyof T, value: number): void;
17
+ }
18
+
19
+ interface HarperTable<T extends { id: string }> {
20
+ get(id: string): Promise<T | undefined>;
21
+ update(id: string): Promise<UpdatableRecord<T>>;
22
+ }
23
+
24
+ declare global {
25
+ const tables: {
26
+ Count: HarperTable<CountRecord>;
27
+ };
28
+ /** Run `callback` in a Harper transaction, committing its writes when it resolves. */
29
+ function transaction<T>(callback: () => T | Promise<T>): Promise<T>;
30
+ }
@@ -0,0 +1,6 @@
1
+ import { withHarper } from '@harperfast/nextjs';
2
+
3
+ // `withHarper` wires this Next.js app into Harper: it marks the `harper` package as a server
4
+ // external so `import 'harper'` resolves to the running Harper runtime (rather than being bundled),
5
+ // giving server-side code access to the `tables` global. Add your own Next.js config inside.
6
+ export default withHarper({});
@@ -0,0 +1,31 @@
1
+ {
2
+ "name": "your-package-name-here",
3
+ "version": "0.0.0",
4
+ "private": true,
5
+ "repository": "github:HarperFast/create-harper",
6
+ "scripts": {
7
+ "agent:run": "npx -y @harperfast/agent@latest",
8
+ "agent:skills:update": "npx -y skills@latest add harperfast/skills --all --yes",
9
+ "start": "next build && harper run .",
10
+ "dev": "next build && harper dev .",
11
+ "build": "next build",
12
+ "lint": "eslint .",
13
+ "format": "prettier --write .",
14
+ "deploy": "next build && harper deploy_component . restart=true replicated=true"
15
+ },
16
+ "dependencies": {
17
+ "@harperfast/nextjs": "^2.2.3",
18
+ "next": "^16.2.11",
19
+ "react": "^19.2.8",
20
+ "react-dom": "^19.2.8"
21
+ },
22
+ "devDependencies": {
23
+ "@types/node": "^24.10.1",
24
+ "@types/react": "^19.2.10",
25
+ "@types/react-dom": "^19.2.3",
26
+ "eslint": "^9.27.0",
27
+ "eslint-config-next": "^16.2.11",
28
+ "prettier": "^3.8.1",
29
+ "typescript": "^5.9.3"
30
+ }
31
+ }
@@ -0,0 +1,5 @@
1
+ # Pre-approve the build scripts for Next.js's native dependencies so `pnpm install` doesn't halt
2
+ # on them (pnpm 10.12+/11 gate dependency build scripts by default). npm and yarn ignore this file.
3
+ allowBuilds:
4
+ sharp: true
5
+ unrs-resolver: true
@@ -0,0 +1,4 @@
1
+ type Count @table @export {
2
+ id: ID @primaryKey
3
+ value: Int
4
+ }
@@ -0,0 +1,23 @@
1
+ {
2
+ "compilerOptions": {
3
+ "target": "ES2017",
4
+ "lib": ["dom", "dom.iterable", "esnext"],
5
+ "allowJs": true,
6
+ "skipLibCheck": true,
7
+ "strict": true,
8
+ "noEmit": true,
9
+ "esModuleInterop": true,
10
+ "module": "esnext",
11
+ "moduleResolution": "bundler",
12
+ "resolveJsonModule": true,
13
+ "isolatedModules": true,
14
+ "jsx": "preserve",
15
+ "incremental": true,
16
+ "plugins": [{ "name": "next" }],
17
+ "paths": {
18
+ "@/*": ["./*"]
19
+ }
20
+ },
21
+ "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
22
+ "exclude": ["node_modules"]
23
+ }