YASK (Yet Another Starter Kit)

Template repository for TypeScript applications. Mostly focuses on back-end code, with the ability to plug in whichever front-end framework you prefer.

Features

• Caching with Redis
• Linting with ESLint
• Unit testing with Vitest
• Formatting with Prettier
• Development in TypeScript
• Pre-push checks with Husky
• ORM and migrations with Drizzle
• Data persistence with PostgreSQL
• Local environment setup with Docker
• Hexagonal dependency injection context
• Continuous integration with GitHub Actions
• Import restrictions with Dependency Cruiser
• Random test data generation with blueprints
• Type-safe environment variable access with Zod

Local development setup

1. Install Docker and Node.js
2. Install Visual Studio Code
3. Clone this repository and open it in Visual Studio Code
4. Install recommended extensions when prompted
5. Setup local environment: cp .env.example .env
6. Start Docker: docker-compose up -d
7. Install dependencies: npm install
8. Setup database: npm run migrate
9. Start development server: npm run dev

package.json scripts

Scripts are organized as parent and child commands, separated by : (e.g. test and test:unit). Parent commands utilize npm-run-all to run all child commands in parallel or sequentially. Parent commands are listed here:

• build: Build the project. This template uses tsc to compile TypeScript files to JavaScript. Depending on your project, you might replace this with a different build tool.
• start: Start the project using the compiled JavaScript files.
• dev: Start the project in development mode. This template watches for changes in the TypeScript files and restarts the server when a change is detected.
• test: Run tests.
• check: Perform code checks (linting, formatting, type checking, etc).
• fix: Fix auto-fixable issues (linting, formatting).
• clean: Delete auto-generated files.
• migrate: Reset database; generate and run migrations.

Directory structure

• src/: The source code for the application itself. Scripts, configurations, etc. that don't directly interact with the application should be put somewhere else.
  • app/: Code specific to your particular application. The template code here will likely be replaced with your own code, but the structure will remain the same.
    • context/: Dependency injection context(s) that define the ports and adapters for your application.
    • repositories/: Persistence-level "repositories" that retrieve and/or mutate database entities.
    • services/: Data and logic "services" that serve as an abstraction between repositories and the front-end.
    • stores/: Cache "stores" that help manage cached data in a type-safe way.
  • db/: Database schema, migrations, and helpers.
    • drizzle/: Drizzle schema definition, migrations, and helpers.
    • blueprints/: Helpers for generating test data in the database.
  • modules/: Generic, non-application-specific utilities. Even though these are non-app-specific, you're free to customize and/or add to them to fit your needs, but keep them decoupled from application-specific logic.
    • cache/: Cache interface and implementations.
    • hexagonal/: Hexagonal architecture implementation.
  • env.ts: Defines the expected shape of process.env and validates it at runtime so it can be accessed with type safety.
• dist/: Compiled JavaScript files. This directory is generated by the build script and is not committed to the repository.
• node_modules/: Node.js dependencies. This directory is generated by npm install and is not committed to the repository.
• .github/: GitHub Actions workflows.
• .husky/: Husky configuration.
• .vscode/: Visual Studio Code settings and recommended extensions.