https://github.com/fells-code/seamless-templates
Template examples for building seamless auth projects
https://github.com/fells-code/seamless-templates
Last synced: 16 days ago
JSON representation
Template examples for building seamless auth projects
- Host: GitHub
- URL: https://github.com/fells-code/seamless-templates
- Owner: fells-code
- License: other
- Created: 2026-06-29T20:14:19.000Z (26 days ago)
- Default Branch: main
- Last Pushed: 2026-07-02T21:50:13.000Z (22 days ago)
- Last Synced: 2026-07-02T23:23:38.350Z (22 days ago)
- Language: TypeScript
- Size: 189 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Seamless Templates
[](LICENSE)
The frontend and API starter templates for [Seamless Auth](https://seamlessauth.com), an open source, passwordless authentication system.
This repository is the single source of truth for the starters that [`seamless-cli`](https://github.com/fells-code/seamless-cli) scaffolds. The CLI reads [`registry.json`](registry.json), presents the available templates during `seamless init`, and copies the chosen ones into a new project already wired to the auth server.
You usually do not clone this repository directly. Run the CLI instead:
```bash
npx seamless-cli init my-app
```
---
## Repository layout
```text
seamless-templates/
├─ registry.json # the catalog the CLI reads to build its prompts
├─ templates/
│ ├─ web/
│ │ └─ / # one directory per web starter
│ │ ├─ template.json # how the CLI fetches and configures this template
│ │ ├─ .env.example # the template's environment contract
│ │ └─ ... # the actual starter project
│ └─ api/
│ └─ / # one directory per API starter
└─ scripts/validate-templates.mjs
```
Each template is a complete, runnable project. The CLI downloads this repository at a pinned tag, copies the selected template directories into the new project (`web/`, `api/`), and fills their `.env` files from each template's declared contract.
---
## The registry
[`registry.json`](registry.json) is the catalog. Every template the CLI can offer has one entry:
```jsonc
{
"schemaVersion": 1,
"templates": [
{
"id": "react-vite", // unique, kebab-case
"kind": "web", // "web" or "api"
"framework": "react",
"label": "React (Vite)", // shown in the CLI prompt
"alias": "basic", // optional: enables `seamless init --basic`
"status": "stable", // "stable" | "beta" | "coming-soon"
"path": "templates/web/react-vite"
}
]
}
```
`status: "coming-soon"` advertises a template in the CLI as a disabled option without requiring its content to exist yet. `alias` (optional) lets users select the template directly with `seamless init --`, skipping the prompt.
## The template manifest
Each template directory carries a `template.json` that tells the CLI where to place it and how to configure its environment. This is what replaces per-framework wiring living inside the CLI:
```jsonc
{
"id": "react-oauth",
"targetDir": "web",
"env": {
"fromExample": ".env.example",
"set": {
"VITE_AUTH_SERVER_URL": "{{authServerUrl}}",
"VITE_API_URL": "{{apiUrl}}"
}
},
"verify": { // optional: how `seamless verify` tests this template
"project": "react", // the Playwright project that drives it
"flows": ["oauth"] // which flow tags to run (@oauth); omit to run all
},
"setup": { // optional: interactive setup the CLI runs
"oauth": true // prompt for OIDC providers and wire them into auth
},
"requires": { "cliMin": "0.3.0" }
}
```
The CLI computes the shared values and resolves the `{{...}}` placeholders in `env.set`. A new framework with different variable names (for example `NEXT_PUBLIC_*`) only needs a different `set` map, not a CLI change.
`verify.flows` scopes conformance to the flows a template actually supports (the harness tags specs `@login`, `@oauth`, ...); a template with no `verify` block runs the full browser suite. `setup.oauth` tells the CLI to prompt for OIDC providers (Google, GitHub, Microsoft, GitLab) and wire the chosen ones into the scaffolded auth server. Both fields are ignored by older CLIs, so they degrade gracefully.
### Placeholder vocabulary
| Placeholder | Resolves to |
| --- | --- |
| `{{authServerUrl}}` | URL of the Seamless Auth server |
| `{{apiUrl}}` | URL of the project's API service |
| `{{apiToken}}` | Service token shared between the API and the auth server |
| `{{jwksKid}}` | JWKS key id the auth server signs with |
| `{{secret:N}}` | A freshly generated N-byte hex secret, unique per scaffold |
---
## Adding a template
1. Create `templates///` with a complete, runnable starter.
2. Add a committed `.env.example` describing its environment contract.
3. Add a `template.json` manifest (see above).
4. Add an entry to `registry.json`.
5. Run `npm run validate` and open a pull request.
CI validates the registry and every manifest, then installs and builds each template to confirm it works before it ships.
---
## Local development
```bash
npm install
npm run validate
```
`npm run validate` checks that `registry.json` is well-formed and that every referenced template has a valid `template.json` and `.env.example`.
---
## Versioning
Releases are managed with [Changesets](https://github.com/changesets/changesets) and published as git tags. The CLI pins a specific tag, so scaffolding is reproducible. Add a changeset with any change that affects scaffolded projects:
```bash
npm run changeset
```
---
## License
AGPL-3.0-only © 2026 Fells Code LLC
See [`LICENSE`](LICENSE) for the full text and [`LICENSE.md`](LICENSE.md) for a summary.