your-project-name-here

Your new app is now deployed and running on Harper Fabric!

Here's what you should do next:

Define Your Schema

1. Create a new yourTableName.graphql file in the schemas directory.
2. Craft your schema by hand or tap "+ New Table" in the action bar for a bit of guidance.
3. Save your changes.
4. Tap "Restart Cluster" and your changes will be live!

These schemas are the heart of a great Harper app, specifying which tables you want and what attributes/fields they should have. Any table you @export stands up endpoints automatically.

Add Custom Endpoints

1. Create a new greeting.ts file in the resources directory.

2. Customize your resource:

   import { type RecordObject, type RequestTargetOrId, Resource } from 'harper';
   
   interface GreetingRecord {
   	greeting: string;
   }
   
   export class Greeting extends Resource<GreetingRecord> {
   	static loadAsInstance = false;
   
   	async post(
   		target: RequestTargetOrId,
   		newRecord: Partial<GreetingRecord & RecordObject>,
   	): Promise<GreetingRecord> {
   		// By default, only super users can access these endpoints.
   		return { greeting: 'Greetings, post!' };
   	}
   
   	async get(target?: RequestTargetOrId): Promise<GreetingRecord> {
   		// But if we want anyone to be able to access it, we can turn off the permission checks!
   		target.checkPermission = false;
   		return { greeting: 'Greetings, get! ' + process.version };
   	}
   
   	async put(
   		target: RequestTargetOrId,
   		record: GreetingRecord & RecordObject,
   	): Promise<GreetingRecord> {
   		target.checkPermission = false;
   		if (this.getCurrentUser()?.name?.includes('Coffee')) {
   			// You can add your own authorization guards, of course.
   			return new Response('Coffee? COFFEE?!', { status: 418 });
   		}
   		return { greeting: 'Sssssssssssssss!' };
   	}
   
   	async patch(
   		target: RequestTargetOrId,
   		record: Partial<GreetingRecord & RecordObject>,
   	): Promise<GreetingRecord> {
   		return { greeting: 'We can make this work!' };
   	}
   
   	async delete(target: RequestTargetOrId): Promise<boolean> {
   		return true;
   	}
   }

3. Save your changes.

4. Tap "Restart Cluster" and your changes will be live!

View Your Website

Pop open http://localhost:9926 to view index.html in your browser.

Use Your API

Head to the APIs tab to explore your endpoints and exercise them. You can click the "Authenticate" button to see what different users will be able to access through your API.

Test your application works by querying the /Greeting endpoint:

curl http://localhost:9926/Greeting

You should see the following:

{ "greeting": "Hello, world!" }

Configure Your App

Take a look at the default configuration, which specifies how files are handled in your application.

One-time setup (private repos)

So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted:

npm run deploy:setup

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.

Public repo? Skip this step and drop credential=true from the deploy script — no credential is needed.

Deploy

npm run deploy

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.

Deploy automatically from CI

The included GitHub Actions workflow deploys whenever you push a version tag:

git tag v1.0.0
git push --tags

Add these repository secrets first, under Settings → Secrets and variables → Actions:

• HARPER_CLI_TARGET — your cluster's operations URL (e.g. https://your-cluster.harperdb.io:9925)
• HARPER_CLI_REFRESH_TOKEN — a long-lived token CI authenticates with, so no password is stored

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:

harper login --for-ci | gh secret set --env-file -

(No gh CLI? harper login --for-ci | pbcopy copies the two lines for you to paste in by hand.)

The clone credential already lives in the cluster from npm run deploy:setup, so CI never handles a token itself.

Private npm dependencies

If your app depends on private npm packages, run npm run deploy:setup again and choose the npm registry — the same sealed-token flow, stored as a separate credential.

Keep Going!

For more information about getting started with Harper and building applications, see our getting started guide.

For more information on Harper Components, see the Components documentation.