Primate LogoPrimate

Project structure

Primate is convention over configuration. This page lists common directories and files used in a Primate app.

Directories

Directory Purpose
build build artefacts — add to .gitignore
client client entrypoints — CSS, JS, fonts
config configuration files
locales I18N locales
node_modules install artefacts — add to .gitignore
pages app and error HTML template pages
routes filesystem-based routes
static static assets served as-is — images, downloads
stores data stores
views frontend views

Files

File Purpose
package.json dependency management
.gitignore add build, node_modules and any other transients
tsconfig.json extend primate/tsconfig
package-lock.json lock file if using npm
pnpm-lock.yaml lock file if using pnpm
bun.lockb lock file if using Bun
yarn.lock lock file if using Yarn

Config files

Reside inside config. May be authored in Javascript or TypeScript.

File Purpose
app.ts app options
session.ts session shape and options
db/*.ts database options

Route files

Files inside the routes directory registered to a backend based on their extension. You may use different backends in your app for different routes, but every route must be uniquely handled by one backend.

File Purpose
index.ts matches /
user.ts matches /user
user/[name].ts matches /user/* — * is anything except a /
user/[[name]].ts matches /user and /user/* — * is anything except a /
user/[...name].ts matches /user/* — * is anything including zero or more /
user/[[...name]].ts matches /user and /user/* — * is anything including zero or more /
+layout.ts route layouts for routes in same directory and below
+hook.ts route hook for routes in same directory and below
+error.ts route error file for routes in same directory

View files

Files inside the views directory registered to a frontend based on their full extensions. You may use different frontends in your app for different views, but every view must be uniquely handled by one frontend.

File Purpose
*.jsx React, Solid or Voby views
*.tsx typed React, Solid or Voby views
*.svelte Svelte views
*.vue Vue views
*.component.ts Angular views
*.marko Marko views
*.eta Eta views
*.html HTML views
*.htmx HTMX views
*.hbs Handlebars views
*.webc Web components

Client files

Files inside the client directory are bundled by Primate and made available as named placeholders in pages/app.html via the entrypoints config option.

Any file type supported by your active frontend modules works here — if you have @primate/svelte configured, you can point an entrypoint at a .svelte file and it will be bundled and injected just like CSS or plain TypeScript.

Store files

Files inside the stores directory, representing data stores. May be authored in JavaScript or TypeScript.

File Purpose
User.ts ORM for user table (import with #store/User in routes)
Post.ts ORM for post table (import with #store/Post in routes)

Locale files

Files inside the locales directory, for I18N.

File Purpose
en-US.ts locale for English (United States)
en-UK.ts locale for English (United Kingdom)
de-DE.ts locale for German (Germany)
Previous
Quickstart
Next
Configuration