Common Build Tools: On some systems (like Linux or macOS), you might need additional build tools (e.g., make, gcc, g++) to install certain dependencies. These are often included in packages like build-essential on Ubuntu or via Xcode Command Line Tools on macOS.
Scaffolding Your First Harper Project
With NPM:
npm create harper@latest
With Yarn:
yarn create harper
With PNPM:
pnpm create harper
With Bun:
bun create harper
With Deno:
deno init --npm harper
Then follow the prompts!
You can also directly specify the project name and the template you want to use via additional command line options. For example, to scaffold a Harper + Vue project, run:
You can use . for the project name to scaffold in the current directory.
Deployment
Every project comes with a GitHub Actions workflow that tests pull requests and deploys to your Harper Fabric cluster when a change merges to main. It stores no Harper credential: the deploy job authenticates with GitHub's OIDC identity token, which the cluster accepts under a trust policy.
After you push the new project to GitHub, set that up once from the project, signed in to the cluster as a super user with harper login, using the Harper 5.4 CLI or later:
npm run deploy:setup-ci
It creates a deploy-only user and the trust policy on the cluster, and sets the workflow's HARPER_CLI_TARGET repository variable. Each project's README covers the rest: going back to an earlier release, staging a release, and what to do when a run is refused.
Most templates can also give each pull request its own preview on the cluster, which takes Harper 5.4 or later there and on your machine. The workflow does nothing until you turn it on, once, with:
npm run deploy:setup-previews
It runs on pull_request_target, which GitHub's default protection blocks for affected public repositories from December 2, 2026, so a public repository must allow that event; the project's README says how. The nextjs and nextjs-ts templates don't have previews yet, because a preview deploys a commit, which has no .next build in it.
Projects created before this deploy on version tags with a stored HARPER_CLI_REFRESH_TOKEN. To move one over, scaffold a new project with the same name, template and package manager, copy its .github/workflows/deploy.yaml over yours, run harper deploy setup=true provider=github-actions project=<the workflow's app: value>, push, and then delete the old secret.
Auto-updates
create-harper will automatically check for newer versions on npm. If a newer version is available, it will automatically re-run the process using the latest version to ensure you are using the most up-to-date templates and features.
If you wish to disable this behavior, you can set the CREATE_HARPER_SKIP_UPDATE environment variable: