{"id":51538584,"url":"https://github.com/fells-code/seamless-templates","last_synced_at":"2026-07-09T11:01:39.608Z","repository":{"id":368940829,"uuid":"1284385928","full_name":"fells-code/seamless-templates","owner":"fells-code","description":"Template examples for building seamless auth projects","archived":false,"fork":false,"pushed_at":"2026-07-02T21:50:13.000Z","size":194,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T23:23:38.350Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fells-code.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-29T20:14:19.000Z","updated_at":"2026-07-02T21:39:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fells-code/seamless-templates","commit_stats":null,"previous_names":["fells-code/seamless-templates"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/fells-code/seamless-templates","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fells-code%2Fseamless-templates","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fells-code%2Fseamless-templates/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fells-code%2Fseamless-templates/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fells-code%2Fseamless-templates/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fells-code","download_url":"https://codeload.github.com/fells-code/seamless-templates/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fells-code%2Fseamless-templates/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35296693,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-09T02:00:07.329Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-09T11:01:38.533Z","updated_at":"2026-07-09T11:01:39.584Z","avatar_url":"https://github.com/fells-code.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Seamless Templates\n\n[![License: AGPL-3.0-only](https://img.shields.io/badge/License-AGPL3-yellow.svg)](LICENSE)\n\nThe frontend and API starter templates for [Seamless Auth](https://seamlessauth.com), an open source, passwordless authentication system.\n\nThis 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.\n\nYou usually do not clone this repository directly. Run the CLI instead:\n\n```bash\nnpx seamless-cli init my-app\n```\n\n---\n\n## Repository layout\n\n```text\nseamless-templates/\n├─ registry.json              # the catalog the CLI reads to build its prompts\n├─ templates/\n│  ├─ web/\n│  │  └─ \u003cframework\u003e/         # one directory per web starter\n│  │     ├─ template.json     # how the CLI fetches and configures this template\n│  │     ├─ .env.example      # the template's environment contract\n│  │     └─ ...               # the actual starter project\n│  └─ api/\n│     └─ \u003cframework\u003e/         # one directory per API starter\n└─ scripts/validate-templates.mjs\n```\n\nEach 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.\n\n---\n\n## The registry\n\n[`registry.json`](registry.json) is the catalog. Every template the CLI can offer has one entry:\n\n```jsonc\n{\n  \"schemaVersion\": 1,\n  \"templates\": [\n    {\n      \"id\": \"react-vite\",          // unique, kebab-case\n      \"kind\": \"web\",               // \"web\" or \"api\"\n      \"framework\": \"react\",\n      \"label\": \"React (Vite)\",     // shown in the CLI prompt\n      \"alias\": \"basic\",            // optional: enables `seamless init --basic`\n      \"status\": \"stable\",          // \"stable\" | \"beta\" | \"coming-soon\"\n      \"path\": \"templates/web/react-vite\"\n    }\n  ]\n}\n```\n\n`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 --\u003calias\u003e`, skipping the prompt.\n\n## The template manifest\n\nEach 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:\n\n```jsonc\n{\n  \"id\": \"react-oauth\",\n  \"targetDir\": \"web\",\n  \"env\": {\n    \"fromExample\": \".env.example\",\n    \"set\": {\n      \"VITE_AUTH_SERVER_URL\": \"{{authServerUrl}}\",\n      \"VITE_API_URL\": \"{{apiUrl}}\"\n    }\n  },\n  \"verify\": {                    // optional: how `seamless verify` tests this template\n    \"project\": \"react\",          // the Playwright project that drives it\n    \"flows\": [\"oauth\"]           // which flow tags to run (@oauth); omit to run all\n  },\n  \"setup\": {                     // optional: interactive setup the CLI runs\n    \"oauth\": true                // prompt for OIDC providers and wire them into auth\n  },\n  \"requires\": { \"cliMin\": \"0.3.0\" }\n}\n```\n\nThe 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.\n\n`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.\n\n### Placeholder vocabulary\n\n| Placeholder | Resolves to |\n| --- | --- |\n| `{{authServerUrl}}` | URL of the Seamless Auth server |\n| `{{apiUrl}}` | URL of the project's API service |\n| `{{apiToken}}` | Service token shared between the API and the auth server |\n| `{{jwksKid}}` | JWKS key id the auth server signs with |\n| `{{secret:N}}` | A freshly generated N-byte hex secret, unique per scaffold |\n\n---\n\n## Adding a template\n\n1. Create `templates/\u003ckind\u003e/\u003cframework\u003e/` with a complete, runnable starter.\n2. Add a committed `.env.example` describing its environment contract.\n3. Add a `template.json` manifest (see above).\n4. Add an entry to `registry.json`.\n5. Run `npm run validate` and open a pull request.\n\nCI validates the registry and every manifest, then installs and builds each template to confirm it works before it ships.\n\n---\n\n## Local development\n\n```bash\nnpm install\nnpm run validate\n```\n\n`npm run validate` checks that `registry.json` is well-formed and that every referenced template has a valid `template.json` and `.env.example`.\n\n---\n\n## Versioning\n\nReleases 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:\n\n```bash\nnpm run changeset\n```\n\n---\n\n## License\n\nAGPL-3.0-only © 2026 Fells Code LLC\n\nSee [`LICENSE`](LICENSE) for the full text and [`LICENSE.md`](LICENSE.md) for a summary.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffells-code%2Fseamless-templates","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffells-code%2Fseamless-templates","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffells-code%2Fseamless-templates/lists"}