A batteries-included TypeScript starter template with comprehensive testing, code quality automation, and security scanning. Built for modern Node.js development with AI-assisted (agentic) coding workflow.
Note: This template includes example code to demonstrate its capabilities. These example files are clearly marked with header comments and should be removed when starting your project. See Getting Started for details.
"Agentic" in this context refers to AI-assisted development workflow, not AI agent runtime. This template is designed to work seamlessly with AI development tools like Claude Code to enhance your productivity through:
- 🤖 AI-powered code generation - Let AI assistants help write boilerplate and tests
- 🔄 Automated refactoring - AI tools can safely refactor with comprehensive test coverage
- 📝 Documentation assistance - AI can help maintain docs in sync with code
- 🎯 Issue-to-implementation workflows - Custom commands for AI-driven development
Important: This is a template repository for starting new projects. No AI agents or chatbots are included - the "agentic" aspect comes from using AI development tools (like Claude) to assist you in building your application faster and with higher quality.
Core: Node.js 22+ • TypeScript ^5.9.2 (strict) • pnpm 10.15
Testing: Vitest • fast-check (property testing) • 80% coverage minimum
Quality: ESLint 9 • Prettier • Husky • Commitlint
Security: CodeQL • OSV Scanner • SBOM • SLSA attestations
CI/CD: GitHub Actions • Changesets • Automated releases
- Getting Started - Setup and installation
- Development - Workflows and commands
- Testing - Test patterns and coverage
- Docker - Docker configuration and healthchecks
- Patterns - Copy-paste code examples
- Troubleshooting - Common issues
# Clone and setup
git clone https://github.com/sapientpants/agentic-node-ts-starter.git my-project
cd my-project
# Install dependencies (requires Node.js 22+ and pnpm 10.15)
pnpm install
# Set up configuration (required)
cp .env.example .env
# Edit .env with your configuration
# See docs/CONFIG.md for required environment variables
# Verify everything works
pnpm test
pnpm verify # Full quality check
# Start developing
pnpm dev # TypeScript watch modePrerequisites: Node.js 22+, pnpm 10.15, GitHub repo (for CI/CD)
Full setup guide: docs/GETTING_STARTED.md
# Development
pnpm dev # TypeScript watch mode
pnpm build # Build to dist/
pnpm verify # Run all quality checks
# Testing (80% coverage required)
pnpm test # Run tests
pnpm test:watch # Watch mode
pnpm test:coverage # With coverage report
# Quality
pnpm lint # Check linting
pnpm lint:fix # Fix linting issues
pnpm format # Check formatting
pnpm format:fix # Fix formatting
pnpm typecheck # Type check only
# Releases
pnpm changeset # Create changeset
pnpm sbom # Generate SBOMFull command reference: docs/DEVELOPMENT.md
This project includes special configurations for Claude Code:
/analyze-and-fix-github-issue- Complete workflow for fixing GitHub issues/release- Automated release process/update-dependencies- Update dependencies with PR workflow
- Prevents bypassing verification with
--no-verifyflag - Ensures all commits pass quality checks
See CLAUDE.md for detailed Claude Code guidance.
.
├── .claude/ # Claude Code configurations
│ ├── commands/ # Custom slash commands
│ └── hooks/ # Git hook scripts
├── .github/ # GitHub Actions workflows
├── docs/ # Documentation
├── src/ # Source code
├── tests/ # Test files
│ ├── *.spec.ts # Unit tests
│ └── *.property.spec.ts # Property-based tests
├── mise.toml # Tool version management
├── package.json # Dependencies and scripts
└── tsconfig.json # TypeScript configuration
- 🔐 Type-safe configuration with Zod validation
- 🔌 Configurable logging output - Redirect logs to stderr, files, syslog, or disable entirely (see docs/LOGGING_OUTPUT.md)
- 🔐 Environment validation at startup with clear errors
- 🔐 Sensitive value masking in error messages
- 📝 See docs/CONFIG.md for configuration guide
- ✅ Vitest with property-based testing (fast-check)
- ✅ 80% coverage minimum enforced
- ✅ Strict TypeScript with type-aware linting
- ✅ Pre-commit hooks with Husky & lint-staged
- ✅ Markdown and YAML linting for docs/config consistency
- 🔒 CodeQL static analysis
- 🔒 OSV Scanner for dependencies
- 🔒 SBOM generation (CycloneDX)
- 🔒 SLSA attestations for artifacts
- 🚀 GitHub Actions CI/CD pipeline
- 🚀 Changesets for versioning
- 🚀 Automated releases with changelog
- 🚀 Claude Code integration
Actions permissions (Settings → Actions → General):
- ✅ Read and write permissions
- ✅ Allow GitHub Actions to create and approve pull requests
Auto-merge (Settings → General → Pull Requests):
- ✅ Allow auto-merge
- ✅ Automatically delete head branches
For automated releases, add secrets:
RELEASE_TOKEN- GitHub PAT with repo/workflow scopes (triggers publish workflow)NPM_TOKEN- For npm publishing (optional)
To enable npm publishing:
- Add
NPM_TOKENsecret in repository settings - Remove
"private": truefrom package.json - Use a scoped package name:
@yourorg/package-name
⚠️ Important: The default Dockerfile includes a healthcheck that expects a web server with a/healthendpoint on port 3000. See Docker Configuration Guide for detailed instructions on configuring healthchecks for different application types (web services, CLI tools, workers).
To enable Docker builds:
- Set repository variable
ENABLE_DOCKER_RELEASEtotrue - Add secrets for Docker Hub (optional):
DOCKERHUB_USERNAMEDOCKERHUB_TOKEN
- Images are automatically pushed to GitHub Container Registry
- Dependency Auditing: Critical vulnerability checks on every CI run
- SBOM Generation: CycloneDX format for supply chain transparency
- CodeQL Analysis: Static security analysis
- OSV Scanning: Open Source Vulnerability detection
- SLSA Provenance: Build attestations
- Container Attestations: SBOM and provenance for Docker images
- Contributing Guide - How to contribute to this project
- Development Process - End-to-end workflow and checklists
- Architecture Decisions - ADR records
This is a template repository. Feel free to use it for your projects.