Installation
Requirements
Section titled “Requirements”- Node.js 20 or later (22 LTS recommended). The
ghuriCLI and Wrangler run on Node even when your app runs on Workers. - npm, pnpm, Bun or Yarn. The examples use npm.
- A Cloudflare account when you want to deploy to Workers. You do not need one to develop
locally:
wrangler devsimulates D1, R2 and KV on your machine. - Postgres 14+ only if you choose the Postgres template or deploy to a VPS.
Create a project
Section titled “Create a project”npm create ghuri@latest mysitecreate-ghuri asks for the project name, the database, the package manager, whether to install
dependencies and whether to initialise a git repository (with an initial commit). Then it runs
ghuri startproject for you and prints the next steps. You can answer the questions up front
with flags:
npm create ghuri@latest mysite -- --db d1 # Cloudflare D1 + R2 (default)npm create ghuri@latest mysite -- --db postgres # Postgres: Hyperdrive on Workers, DATABASE_URL elsewherenpm create ghuri@latest mysite -- --db sqlite # Node.js project: better-sqlite3 + local files, no Cloudflare| Option | Default | Meaning |
|---|---|---|
[name] |
asked (my-ghuri-app with --yes) |
Project name and directory. Letters, digits, - and _, starting with a letter. |
--db <d1|postgres|sqlite> |
d1 |
Database the generated settings.ts, wrangler.jsonc and .dev.vars use. |
--pm <npm|pnpm|bun|yarn> |
the one you ran create with |
Package manager for installing and for the printed commands. |
--install / --no-install |
yes | Install dependencies. |
--git / --no-git |
yes | git init plus an initial commit. |
-y, --yes |
Never prompt; use defaults for anything not given. |
Prompts are skipped automatically when stdin is not a terminal (CI). You can also skip
create-ghuri and run the CLI directly: npx @ghuri/cli@next startproject mysite --db d1.
The --db choice only decides what goes into the generated files, and every template already
switches to Postgres when DATABASE_URL is set. You can change databases later by editing
settings, so do not agonise over it. If you are unsure, take the default.
Run it
Section titled “Run it”cd mysitenpx ghuri migrate # create the tables for auth, sessions, tokens and the adminnpx ghuri createsuperuser # an admin usernpm run devnpm run dev runs ghuri runserver, which starts wrangler dev on http://localhost:8787
(for a --db sqlite project it runs ghuri runserver --node on http://localhost:8000).
The root URL answers with a small JSON document from the home view in src/urls.ts; the admin
is at /admin/ and the REST API root at /api/.
Local development works with the placeholder database_id in wrangler.jsonc. You only need
to run npx wrangler d1 create mysite-db and paste the real id when you
deploy.
The secret key
Section titled “The secret key”Ghuri signs sessions, CSRF tokens and password reset links with SECRET_KEY. startproject
generates a random one into .dev.vars, which Wrangler and the ghuri CLI both load:
# Local development variables (read by wrangler and ghuri). Never commit this file.SECRET_KEY=q3N…64 random characters…DEBUG=true.dev.vars is git-ignored; .dev.vars.example is the committed template for your teammates.
For production you set the secret with npx wrangler secret put SECRET_KEY (Workers) or an
environment variable (Node). Settings refuse to load without a SECRET_KEY unless DEBUG is
on.
Adding Ghuri to an existing Workers project
Section titled “Adding Ghuri to an existing Workers project”The create-ghuri template is the supported path, but nothing in it is magic. To add Ghuri by
hand, install the packages under the next tag:
npm install @ghuri/core@next @ghuri/orm@next @ghuri/auth@next @ghuri/rest@next \ @ghuri/storage@next @ghuri/admin@next hono drizzle-ormnpm install -D @ghuri/cli@next wrangler typescript vitestThen:
- Make sure
wrangler.jsonchas"compatibility_flags": ["nodejs_compat"]. Ghuri usesAsyncLocalStoragefromnode:async_hooksto carry the request context. - Add
"ghuri": { "settings": "src/settings.ts" }topackage.jsonso the CLI can find your settings (without it the CLI looks forsrc/settings.ts). - Write a
settings.ts(see Settings and Project layout) and exportcreateApp(settings)as the Worker’s default export.
The easiest way to get a correct starting point is to generate a throwaway project with
npx @ghuri/cli@next startproject scratch --no-install and copy what you need from it.
Editor setup
Section titled “Editor setup”Ghuri is written for strict TypeScript with moduleResolution: "bundler", and the generated
tsconfig.json already has the right options:
{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "bundler", "lib": ["ES2023"], "types": ["@cloudflare/workers-types", "node"], "strict": true, "skipLibCheck": true, "isolatedModules": true, "noEmit": true, // Hono JSX for server-rendered views "jsx": "react-jsx", "jsxImportSource": "hono/jsx" // Ghuri uses standard (TC39) decorators: @admin.register, @action. // You do not need "experimentalDecorators". }, "include": ["src", "vitest.config.ts"]}npm run typecheck runs tsc --noEmit over the project.
Next steps
Section titled “Next steps”Take a look at what startproject generated, then
start the tutorial.