Contributing
Ghuri is developed in the open under the ghurijs organisation on GitHub. Bug reports, documentation fixes and pull requests are welcome.
Repository layout
Section titled “Repository layout”Each package lives in its own repository and publishes to npm under the @ghuri scope:
| Repository | npm package | Contents |
|---|---|---|
ghurijs/ghuri |
(private) | Meta repo: the architecture spec, roadmap, development workspace and bootstrap script |
ghurijs/core |
@ghuri/core |
settings, apps, URLs, views, middleware, context, signals, cache, commands, testing client, Node adapter |
ghurijs/orm |
@ghuri/orm |
models, fields, QuerySets, relations, database adapters, migrations |
ghurijs/auth |
@ghuri/auth |
users, permissions, sessions, tokens, JWT |
ghurijs/rest |
@ghuri/rest |
the REST framework |
ghurijs/storage |
@ghuri/storage |
storage backends, FileField |
ghurijs/admin |
@ghuri/admin |
the admin site |
ghurijs/graphql |
@ghuri/graphql |
GraphQL (graphene-django style) |
ghurijs/realtime |
@ghuri/realtime |
WebSockets (Django Channels style) |
ghurijs/oauth |
@ghuri/oauth |
login strategies: OAuth2, OpenID Connect, magic link |
ghurijs/socialauth |
@ghuri/socialauth |
social login (django-allauth style) |
ghurijs/mail |
@ghuri/mail |
sending email |
ghurijs/tenants |
@ghuri/tenants |
shared-schema multi-tenancy |
ghurijs/agents |
@ghuri/agents |
AI agents and the MCP server |
ghurijs/cli |
@ghuri/cli |
the ghuri command |
ghurijs/create-ghuri |
create-ghuri |
npm create ghuri@latest |
ghurijs/examples |
(private) | example projects, used as end-to-end tests |
ghurijs/docs |
(private) | this site |
The architecture spec
Section titled “The architecture spec”ARCHITECTURE.md in the meta repo is the source of truth for every package’s public API. Its
last section, “As-built notes”, records where the implementation deliberately differs from the
earlier sections and wins over them. Packages
talk to each other only through the contracts written there: for example, the REST framework
reads Model._meta and Field.jsonSchema(), and the admin reads Field.formHint(), without
importing ORM internals.
If a change needs a contract that does not exist, add it to the spec first (in the same pull
request, or a linked one against ghurijs/ghuri), then implement it.
Setting up the workspace
Section titled “Setting up the workspace”The meta repo is an npm workspace that holds every package side by side:
git clone https://github.com/ghurijs/ghuricd ghurinpm run bootstrapnpm run bootstrap runs scripts/bootstrap.sh, which:
- clones each package repository (
core,orm,auth,rest,storage,admin,agents,cli,create-ghuri) intopackages/<repo>(git-ignored by the meta repo), - clones
examplesintoexamples/, - runs
npm installat the root, linking the packages to each other, and - builds every package.
Sibling dependencies use the range ^0.1.0-alpha.0, which npm workspaces resolve to the local
clones, so a change in packages/orm is visible to packages/rest after rebuilding.
Useful commands from the workspace root:
npm run build # build every package (tsup)npm test # run every package's tests (vitest)npm run typecheck # tsc --noEmit everywhereEach package is still its own git repository. Commit and open pull requests from inside
packages/<name>.
The docs site is not part of the workspace. Clone ghurijs/docs
separately (or into docs/ inside the meta repo), then:
cd docsnpm installnpm run dev # http://localhost:4321/docs/Every page has an Edit page link at the bottom that opens the source file on GitHub.
Conventions
Section titled “Conventions”- ESM only, TypeScript
~5.9withstrict: true, target ES2022,moduleResolution: bundler. - Builds use
tsup(ESM plus.d.ts) intodist/. Subpath exports are declared inpackage.json#exports. - Workers compatibility. Every package must run on Workers with
nodejs_compat. Never import Node-only modules (fs,path,better-sqlite3,pg) from a package’s main entry; put them behind a subpath such as@ghuri/orm/sqliteor@ghuri/core/node, or a dynamic import. - Global state (the app registry, the request context, the model registry) must survive the
package being loaded twice, so packages list
@ghuri/*siblings aspeerDependencies. - Naming. Classes are
PascalCase; options and fields arecamelCase; settings keys stayUPPER_SNAKE; database columns aresnake_case. - Errors extend
GhuriErrorfrom@ghuri/core. - Public API is what
src/index.tsand declared subpaths export. Everything else is internal and may change without notice. - Tests use Vitest on Node. Database tests run against SQLite (better-sqlite3), PGlite
(Postgres dialect) and D1 (Miniflare) where relevant;
testBackends()from@ghuri/orm/testingreadsGHURI_TEST_BACKENDS=sqlite,pgliteto narrow the set. - Decorators are standard TC39 decorators. Vite 8 (oxc) does not lower them yet, so packages
that use them in tests lower them in
vitest.config.ts(an esbuild pre-transform, or oxc’s legacy decorator mode). - Lint and format with Biome (each package has its own
biome.json).
Commits and pull requests
Section titled “Commits and pull requests”Commit messages follow Conventional Commits, scoped to the package:
feat(orm): support __iregex lookup on Postgresfix(admin): keep filters when paginating the change listdocs(rest): document CursorPagination orderingA good pull request:
- links the issue it fixes, or explains the problem it solves;
- includes tests, on every database dialect the change touches;
- updates the package’s
README.mdandCHANGELOG.mdwhen behaviour changes; - updates
ARCHITECTURE.md(in the meta repo) when it changes a public contract; - updates these docs when it changes anything a user would notice.
Reporting bugs
Section titled “Reporting bugs”Open an issue on the repository of the package involved. Include the Ghuri package versions
(npx ghuri version), the runtime (Workers or Node, and the version), the database, a minimal
reproduction, and what you expected to happen. If you are not sure which package is responsible,
open it on ghurijs/ghuri.
License
Section titled “License”Ghuri is released under the MIT license.