Contributing

Titanbase is built in the open under Apache-2.0, and contributions are welcome. This page covers local setup and the contribution workflow.

Prerequisites#

• Node.js 20+
• pnpm (for the core monorepo)
• Git

Run the app and packages#

The editor, schema engine, and exporters live in the core monorepo:

git clone https://github.com/titanbaserun/titanbase
cd titanbase
pnpm install
pnpm dev          # start the web app (editor) in dev mode

Run the tests#

pnpm test         # run the test suite
pnpm typecheck    # type-check the workspace
pnpm build        # build all packages

Run the docs locally#

The documentation site is a separate Next.js project:

cd docs
npm install
npm run dev       # serve the docs locally
npm run build     # production build
npm run typecheck

Ways to contribute#

Add a new exporter#

Exporters are the easiest way to contribute — each is a pure function from TitanSchema to output. Implement it against the Plugin API and use the existing @titanbase/export-mermaid, @titanbase/export-prisma, and @titanbase/export-drizzle packages as references. Add tests that cover type mapping, constraints, and warning behavior.

Add or update templates#

Templates live in examples/. A template is a valid .titan.json. When adding one:

• give it a clear, real-world domain;
• make sure it has no validation errors;
• only leave warnings when they are intentional (see template quality).

Add a diagnostic#

Schema checks live in @titanbase/core (diagnostics.ts). When adding a check, give it a stable code, the right severity (error / warning / info), a clear message, and a help hint where useful. Add tests for both the passing and failing cases, and document it on the Diagnostics page.

Keep .titan.json docs in sync

When the schema types or Zod schemas in @titanbase/core change, update the .titan.json format reference and type system so the documented shape matches the code. The docs should never claim a field or type the code does not support.

Report a bug#

Open an issue with a description, steps to reproduce, expected vs. actual behavior, and your .titan.json if relevant (anonymize names as needed).

Suggest a feature#

Open an issue tagged feature-request. Describe the use case first, then the proposed solution.

Submitting code#

1. Fork the repository.
2. Create a branch from main: git checkout -b feat/my-feature.
3. Make your changes and add or update tests.
4. Run pnpm test, pnpm typecheck, and pnpm build.
5. Open a pull request against main.

Code style#

• TypeScript strict mode
• Prefer unknown with narrowing over any
• Functional style over classes
• Tests with Vitest; format with Prettier; lint with ESLint

Commit messages#

Follow conventional commits:

feat(core): add enum support to the schema model
fix(pg): handle nullable uuid columns
docs: clarify many-to-many relations
test(prisma): cover enum value mapping

License#

By contributing, you agree that your contributions are licensed under Apache-2.0.