{"id":31663916,"url":"https://github.com/sciexp/typescript-nix-template","last_synced_at":"2026-03-16T07:10:15.656Z","repository":{"id":318414792,"uuid":"1070258827","full_name":"sciexp/typescript-nix-template","owner":"sciexp","description":"❄️ nix template for typescript monorepos with bun workspaces +/- astro starlight and flake-parts 💫","archived":false,"fork":false,"pushed_at":"2026-01-18T03:30:53.000Z","size":974,"stargazers_count":0,"open_issues_count":12,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-18T14:59:06.671Z","etag":null,"topics":["astro","biomejs","bun","cloudflare","flake-parts","just","monorepo","nix","nix-flake","playwright","rolldown","sops","starlight","tanstack","template-project","typescript","vite","vitest","wrangler"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sciexp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/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":null,"dco":null,"cla":null}},"created_at":"2025-10-05T15:32:02.000Z","updated_at":"2026-01-12T15:04:13.000Z","dependencies_parsed_at":"2025-10-07T04:23:59.290Z","dependency_job_id":null,"html_url":"https://github.com/sciexp/typescript-nix-template","commit_stats":null,"previous_names":["sciexp/typescript-nix-template"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/sciexp/typescript-nix-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sciexp%2Ftypescript-nix-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sciexp%2Ftypescript-nix-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sciexp%2Ftypescript-nix-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sciexp%2Ftypescript-nix-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sciexp","download_url":"https://codeload.github.com/sciexp/typescript-nix-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sciexp%2Ftypescript-nix-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28563234,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T03:31:16.861Z","status":"ssl_error","status_checked_at":"2026-01-19T03:31:15.069Z","response_time":67,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["astro","biomejs","bun","cloudflare","flake-parts","just","monorepo","nix","nix-flake","playwright","rolldown","sops","starlight","tanstack","template-project","typescript","vite","vitest","wrangler"],"created_at":"2025-10-07T20:51:49.838Z","updated_at":"2026-01-19T08:02:32.180Z","avatar_url":"https://github.com/sciexp.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# typescript-nix-template\n\nTypeScript project template with Nix flake-parts, Bun workspaces, and semantic-release.\n\n## Overview\n\nThis is a monorepo workspace combining TypeScript packages with a Nix flake that uses deferred module composition via import-tree.\nThe architecture provides reproducible development environments, unified formatting with treefmt-nix, and comprehensive testing including nix-unit tests for flake validation.\n\n## Prerequisites\n\n### Quick start (one-liner)\n\nInstall Nix, direnv, and generate secrets keys with a single command.\nFirst, preview what the script will do:\n\n```bash\nbash \u003c(curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/sciexp/typescript-nix-template/main/scripts/bootstrap.sh) --dry-run\n```\n\nOnce you're comfortable with the actions it will take, remove `--dry-run` to execute.\nUse `--help` to see all options including `--yes` for non-interactive mode.\n\n\u003cdetails\u003e\n\u003csummary\u003eManual bootstrap\u003c/summary\u003e\n\nAlternatively, clone first and use Make targets:\n\n```bash\ngit clone https://github.com/sciexp/typescript-nix-template.git\ncd typescript-nix-template\n\n# On macOS: install Xcode CLI tools and Homebrew\nmake bootstrap-prep-darwin\n\n# Install Nix and direnv\nmake bootstrap\n\n# Verify and generate secrets key\nmake verify\nmake setup-user\n```\n\n\u003c/details\u003e\n\n### Setup (Nix already installed)\n\n```bash\ngit clone https://github.com/sciexp/typescript-nix-template.git\ncd typescript-nix-template\nnix develop\nbun install\n```\n\n## Template usage\n\nYou can use [omnix](https://omnix.page/om/init.html)[^omnix] to initialize this template:\n\n```sh\nnix --accept-flake-config run github:juspay/omnix -- \\\n  init github:sciexp/typescript-nix-template -o my-project\n```\n\n[^omnix]: If you have omnix installed you just need `om init ...` and not `nix run ... -- init`\n\nYou can run `direnv allow` to enter the shell environment that contains development dependencies or `nix develop` to enter (or add `-c command` to execute individual commands within) the development shell.\n\n\u003cdetails\u003e\u003csummary\u003eInstantiate with full parameters\u003c/summary\u003e\n\n```sh\nPROJECT_DIRECTORY=my-project \u0026\u0026 \\\nPARAMS=$(cat \u003c\u003cEOF\n{\n  \"project-name\": \"$PROJECT_DIRECTORY\",\n  \"npm-scope\": \"@$PROJECT_DIRECTORY\",\n  \"git-org\": \"myorg\",\n  \"author\": \"Your Name\",\n  \"author-email\": \"you@example.com\",\n  \"project-description\": \"My TypeScript project with Nix\",\n  \"cloudflare-worker-name\": \"my-project-docs\",\n  \"production-url\": \"my-project.example.com\",\n  \"github-ci\": true,\n  \"vscode\": true,\n  \"docs\": true,\n  \"nix-template\": false\n}\nEOF\n) \u0026\u0026 \\\nnix --accept-flake-config run github:juspay/omnix/v1.3.0 -- \\\n  init github:sciexp/typescript-nix-template/main \\\n  -o \"$PROJECT_DIRECTORY\" --non-interactive --params \"$PARAMS\" \u0026\u0026 \\\ncd \"$PROJECT_DIRECTORY\" \u0026\u0026 \\\ngit init \u0026\u0026 \\\ngit commit --allow-empty -m \"initial commit (empty)\" \u0026\u0026 \\\ngit add . \u0026\u0026 \\\ndirenv allow \u0026\u0026 \\\nbun install \u0026\u0026 \\\nbun test\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eInstantiate without docs (minimal)\u003c/summary\u003e\n\nFor projects that do not need a documentation site or Cloudflare deployment:\n\n```sh\nPROJECT_DIRECTORY=my-project \u0026\u0026 \\\nPARAMS=$(cat \u003c\u003cEOF\n{\n  \"project-name\": \"$PROJECT_DIRECTORY\",\n  \"npm-scope\": \"@$PROJECT_DIRECTORY\",\n  \"git-org\": \"myorg\",\n  \"author\": \"Your Name\",\n  \"author-email\": \"you@example.com\",\n  \"project-description\": \"My TypeScript project with Nix\",\n  \"cloudflare-worker-name\": \"\",\n  \"production-url\": \"\",\n  \"github-ci\": true,\n  \"vscode\": true,\n  \"docs\": false,\n  \"nix-template\": false\n}\nEOF\n) \u0026\u0026 \\\nnix --accept-flake-config run github:juspay/omnix/v1.3.0 -- \\\n  init github:sciexp/typescript-nix-template/main \\\n  -o \"$PROJECT_DIRECTORY\" --non-interactive --params \"$PARAMS\" \u0026\u0026 \\\ncd \"$PROJECT_DIRECTORY\" \u0026\u0026 \\\ngit init \u0026\u0026 \\\ngit commit --allow-empty -m \"initial commit (empty)\" \u0026\u0026 \\\ngit add . \u0026\u0026 \\\ndirenv allow \u0026\u0026 \\\nbun install \u0026\u0026 \\\nbun test\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eVersion pinning options\u003c/summary\u003e\n\nYou may want to update the git ref/rev of the template if you need to pin to a particular version:\n\n- `github:sciexp/typescript-nix-template/main`\n- `github:sciexp/typescript-nix-template/v0.1.0`\n- `github:sciexp/typescript-nix-template/3289dla`\n- `github:sciexp/typescript-nix-template/devbranch`\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eTemplate parameters\u003c/summary\u003e\n\n| Parameter | Description |\n| :-------- | :---------- |\n| `project-name` | Project/repository name (kebab-case) |\n| `npm-scope` | npm package scope (include the `@` prefix) |\n| `git-org` | GitHub organization or username |\n| `author` | Package author name |\n| `author-email` | Package author email |\n| `project-description` | Short description of the project |\n| `cloudflare-worker-name` | Cloudflare Pages worker identifier (empty string if `docs: false`) |\n| `production-url` | Production domain for docs site (empty string if `docs: false`) |\n| `github-ci` | Enable GitHub Actions workflows |\n| `vscode` | Include VS Code workspace configuration |\n| `docs` | Include Astro Starlight documentation site |\n| `nix-template` | Include template.nix for re-templating capability |\n\n\u003c/details\u003e\n\n## Packages\n\n- **[@typescript-nix-template/docs](./packages/docs)**: Astro Starlight documentation site [![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)\n\n\u003cdetails\u003e\u003csummary\u003eProject structure\u003c/summary\u003e\n\n```\ntypescript-nix-template/\n├── modules/                     # Nix flake-parts modules (import-tree)\n│   ├── checks/\n│   │   └── nix-unit.nix         # Flake validation tests\n│   ├── dev-shell.nix            # Development environment\n│   ├── flake-parts.nix          # Module composition\n│   ├── formatting.nix           # treefmt-nix configuration\n│   ├── packages.nix             # Nix package definitions\n│   ├── systems.nix              # Supported system architectures\n│   └── template.nix             # Flake template definition\n├── packages/\n│   └── docs/                    # Astro Starlight documentation site\n│       ├── src/\n│       ├── public/\n│       ├── e2e/\n│       ├── tests/\n│       └── package.json\n├── package.json                 # Workspace root configuration\n├── tsconfig.json                # Shared TypeScript configuration\n├── flake.nix                    # Nix flake entrypoint\n├── Makefile                     # Bootstrap commands (nix/direnv install)\n├── justfile                     # Development task runner\n└── CONTRIBUTING.md              # Contribution guidelines\n```\n\n\u003c/details\u003e\n\n## Nix architecture\n\nThis template uses flake-parts with import-tree for deferred module composition.\nModules in the `modules/` directory are automatically discovered and composed, separating concerns by aspect rather than bundling everything in `flake.nix`.\n\nKey modules:\n- **formatting.nix**: treefmt-nix configuration with biome (TypeScript/JSON) and nixfmt (Nix)\n- **dev-shell.nix**: Development tools (bun, biome, playwright, semantic-release, etc.)\n- **packages.nix**: Nix package definitions for the docs site\n- **checks/nix-unit.nix**: Flake validation tests ensuring outputs conform to expected structure\n\n### Formatting\n\nAll formatting runs through treefmt-nix, providing a single command for all file types:\n\n```bash\nnix fmt                    # Format all files\njust fmt                   # Alias via just\njust fmt-check             # Check without modifying\n```\n\nFormatters configured: biome (TypeScript, JSON, JavaScript), nixfmt (Nix files).\n\n### Flake validation\n\n```bash\nnix flake check --impure   # Run all checks including nix-unit tests\njust check                 # Alias via just\njust validate-flake        # Validate flake structure and required recipes\n```\n\n## Development\n\n### Workspace commands\n\n```bash\n# Install all workspace dependencies\njust install\n\n# Clean all build artifacts\njust clean\n\n# Run command in specific package\njust pkg docs \u003ccommand\u003e\n\n# Run command in docs (shorthand)\njust docs \u003ccommand\u003e\n```\n\n### Package-specific commands\n\n```bash\n# Start dev server for docs\njust docs-dev\n\n# Build docs\njust docs-build\n\n# Run tests\njust test\n\n# Run unit tests\njust docs-test-unit\n\n# Run E2E tests\njust docs-test-e2e\n```\n\n\u003cdetails\u003e\u003csummary\u003eUsing bun directly\u003c/summary\u003e\n\n```bash\n# Run command in specific package\nbun run --filter '@typescript-nix-template/docs' dev\nbun run --filter '@typescript-nix-template/docs' build\nbun run --filter '@typescript-nix-template/docs' test\n\n# Run command in all packages\nbun run --filter '@typescript-nix-template/*' test\n```\n\n\u003c/details\u003e\n\n## Testing\n\nComprehensive testing with Vitest and Playwright:\n\n| Command                | Action                                    |\n| :--------------------- | :---------------------------------------- |\n| `just test`            | Run all tests in all packages             |\n| `just test-pkg \u003cname\u003e` | Run tests in specific package             |\n| `just test-unit`       | Run unit tests in docs                    |\n| `just test-e2e`        | Run E2E tests in docs                     |\n| `just test-watch`      | Run Vitest in watch mode                  |\n| `just test-ui`         | Run Playwright in UI mode                 |\n| `just test-coverage`   | Generate test coverage report             |\n\n## Deployment\n\n### Cloudflare Workers\n\nThe docs package deploys to Cloudflare Workers:\n\n```bash\n# Preview locally\njust cf-preview\n\n# Deploy preview for branch\njust docs-deploy-preview \u003cbranch\u003e\n\n# Deploy to production\njust docs-deploy-production\n```\n\n## Releases\n\nThis project uses [semantic-release](https://semantic-release.gitbook.io/) with [conventional commits](https://www.conventionalcommits.org/) for automated versioning.\n\n### Commit format\n\n```\n\u003ctype\u003e(\u003cscope\u003e): \u003csubject\u003e\n```\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.\n\n### Testing releases\n\n```bash\n# Test release for specific package\njust test-release docs\n\n# Test release for all packages\njust test-release-all\n```\n\n## CI/CD\n\nGitHub Actions workflows use category-based matrix builds for efficient parallelization:\n\n- **nix**: Flake checks and builds distributed across `packages`, `checks`, `devShells`, and `formatter` categories\n- **package-test**: Unit tests, coverage, and E2E tests for each package\n- **deploy-docs**: Preview and production deployments to Cloudflare Workers\n\n\u003cdetails\u003e\u003csummary\u003eLocal CI equivalence\u003c/summary\u003e\n\nAny CI job can be reproduced locally using the same commands:\n\n```bash\nnix develop -c just check              # Flake validation\nnix develop -c just ci-build-category aarch64-darwin packages  # Build specific category\nnix develop -c just scan-secrets       # Security scanning\n```\n\n\u003c/details\u003e\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines and conventional commit format.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsciexp%2Ftypescript-nix-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsciexp%2Ftypescript-nix-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsciexp%2Ftypescript-nix-template/lists"}