Dossier

Dossier enables you to build solutions where you’re in full control of the content. By bringing your own auth (authentication and authorization), database and backend, you can build a headless Content Management System (CMS) and integrate it with your app.

For more information about Dossier, head over to dossierhq.dev. The rest of this readme is focused on developing and contributing to Dossier itself.

If you just want to get started using Dossier, these destinations might get you there faster:

• Dossier Playground - use Dossier in a browser
• dossier-next-sqlite-app - a template using Dossier, Next.js and SQLite
• dossier-astro-sqlite-app - a template using Dossier, Astro and SQLite

Published packages

Package	Version	Folder
@dossierhq/better-sqlite3		libraries/better-sqlite3
@dossierhq/cloudinary		libraries/cloudinary
@dossierhq/core		libraries/core
@dossierhq/core-vitest		libraries/core-vitest
@dossierhq/database-adapter		libraries/database-adapter
@dossierhq/design		libraries/design
@dossierhq/graphql		libraries/graphql
@dossierhq/integration-test		libraries/integration-test
@dossierhq/leaflet		libraries/leaflet
@dossierhq/pg		libraries/pg
@dossierhq/postgres-core		libraries/postgres-core
@dossierhq/postgres-tools		libraries/postgres-tools
@dossierhq/react-components		libraries/react-components
@dossierhq/server		libraries/server
@dossierhq/sql.js		libraries/sql.js
@dossierhq/sqlite-core		libraries/sqlite-core
@dossierhq/typescript-generator		libraries/typescript-generator

Development dependencies

• Use asdf to install the tools in .tools-versions
  • asdf plugin add libsql-server https://github.com/jonasb/asdf-libsql-server.git
• npm install -g @microsoft/rush
• brew install pgcli (optional, for Postgres access)
• brew install gnuplot (for benchmarking)
• npx playwright install (for installing browsers for Playwright testing)

Getting started

• rush update to install dependencies.
• In tools/generic-tools/:
  • By default the databases (test and example databases on PostgreSQL) are configured in Docker. To use another db set the env variable HOST_ROOT_DATABASE_URL
  • npm run db:start (only if running db in Docker)
  • npm run db:ensure-dbs
  • npm run db:make-users:superuser
  • npm run db:migrate:all
  • npm run db:make-users:no-superuser
• rush build

Dev container / Github Code Spaces

• Start dev container
• The script post-create.sh runs automatically on first run
• When done, restart your shell since it sets up environment variables
• For root access to the Postgres database, run psql "$HOST_ROOT_DATABASE_URL" or pgcli "$HOST_ROOT_DATABASE_URL"

Dependencies

• Run rush add --package foo instead of npm install foo (rush add --package foo --dev instead of npm install --save-dev foo)
• Run cd tools/all-dependencies && npm run build
• Check that the same versions of dependencies are used, run rush check.

Upgrade dependencies

• Upgrade tool versions in .tool-versions
• Update rushVersion and pnpmVersion in rush.json (npm show @microsoft/rush version/npm show pnpm version – or use same version as rush: rush.json)
• Upgrade individual dependencies in tools/all-dependencies/:
  • npm run outdated to get a list of outdated dependencies
  • rush add --package typescript@latest --dev --make-consistent
  • or rush upgrade-interactive
• Upgrade Deno dependencies in the 3 import-map.json files
• Run (cd tools/generic-tools && npm run deno:reload-dependencies:all)
• Upgrade the postgres version in ./docker-compose.yml

Publish packages

• Normally publishing the packages bumps the patch version, change nextBump to minor in common/config/rush/version-policies.json to bump minor instead
• rush change
• git add common/changes/ && git commit
• git push
• Start publish workflow
• When done, change back nextBump to patch if you changed it

Ports

• 3000: examples/tutorial
• 3001: examples/next-web
• 3002: apps/playground
• 3003: apps/blog
• 4321: examples/astro
• 4322: examples/astro (HMR)
• 5173: examples/tutorial
• 6006: libraries/react-components
• 6007: libraries/design
• 9000: libraries/libsql - admin entity
• 9001: libraries/libsql - advisory lock
• 9002: libraries/libsql - advisory lock
• 9003: libraries/libsql - published entity
• 9004: libraries/libsql - schema
• 9005: libraries/libsql - changelog