{"id":31908211,"url":"https://github.com/nodejs-boot/sample-express","last_synced_at":"2026-04-15T22:32:55.072Z","repository":{"id":317883524,"uuid":"1069220734","full_name":"nodejs-boot/sample-express","owner":"nodejs-boot","description":"Node-Boot sample project using Express.js server","archived":false,"fork":false,"pushed_at":"2025-10-03T15:53:25.000Z","size":599,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-21T20:58:14.149Z","etag":null,"topics":["express","expressjs","node-boot","nodeboot","nodejs","sample","seed"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nodejs-boot.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":null,"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-03T15:31:44.000Z","updated_at":"2025-10-03T15:54:29.000Z","dependencies_parsed_at":"2025-10-03T17:56:16.111Z","dependency_job_id":"49496035-454f-41a9-a053-e86b62024919","html_url":"https://github.com/nodejs-boot/sample-express","commit_stats":null,"previous_names":["nodejs-boot/sample-express"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nodejs-boot/sample-express","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodejs-boot%2Fsample-express","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodejs-boot%2Fsample-express/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodejs-boot%2Fsample-express/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodejs-boot%2Fsample-express/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nodejs-boot","download_url":"https://codeload.github.com/nodejs-boot/sample-express/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodejs-boot%2Fsample-express/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31863492,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: 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":["express","expressjs","node-boot","nodeboot","nodejs","sample","seed"],"created_at":"2025-10-13T15:24:37.575Z","updated_at":"2026-04-15T22:32:55.016Z","avatar_url":"https://github.com/nodejs-boot.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Node-Boot Express Sample\n\nA comprehensive sample Node-Boot application using Express.js framework that demonstrates best practices for building scalable TypeScript applications with dependency injection, validation, persistence, and more.\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Node.js (LTS version recommended)\n- pnpm (package manager)\n- SQLite (for local development)\n\n### Installation \u0026 Setup\n\n1. **Clone and install dependencies:**\n   ```bash\n   git clone https://github.com/nodejs-boot/sample-express.git\n   cd sample-express\n   pnpm install\n   ```\n\n2. **Start development server:**\n   ```bash\n   pnpm star\n   \n   #or with nodemon for hot reload\n   pnpm dev\n   ```\n\n![run](assets/run.png)\n\n3. **Access the application:**\n    - API: http://localhost:3000/api\n    - Swagger UI: http://localhost:3000/docs\n    - Actuator Metrics/info: http://localhost:3000/actuator\n    - Health Check: http://localhost:3000/actuator/health\n\n4. **Actuator Endpoints:**\n    - `/actuator/health` - Application health status\n    - `/actuator/info` - Application info\n    - `/actuator/git` - Git info\n    - `/actuator/config` - Current configuration\n    - `/actuator/metrics` - Application metrics\n    - `/actuator/prometheus` - Prometheus metrics\n    - `/actuator/controllers` - Registered controllers\n    - `/actuator/interceptors` - Registered interceptors\n    - `/actuator/middlewares` - Registered middlewares\n\n## 📋 Available Scripts\n\n| Script                  | Description                                                    |\n|-------------------------|----------------------------------------------------------------|\n| `pnpm start`            | Build and start production server                              |\n| `pnpm start:prod`       | Build and start with NODE_ENV=production                       |\n| `pnpm dev`              | Start development server with hot reload                       |\n| `pnpm build`            | Compile TypeScript to JavaScript                               |\n| `pnpm postbuild`        | Run Node-Boot AOT (Ahead of Time) compilation                  |\n| `pnpm clean:build`      | Remove dist directory                                          |\n| `pnpm lint`             | Run ESLint                                                     |\n| `pnpm lint:fix`         | Run ESLint with auto-fix                                       |\n| `pnpm format`           | Check code formatting                                          |\n| `pnpm format:fix`       | Format code with Prettier                                      |\n| `pnpm test`             | Run tests with Jest                                            |\n| `pnpm typecheck`        | Type check without compilation                                 |\n| `pnpm nodeboot:update`  | Update Node-boot framework - Update all `@nodeboot` packages   |\n| `pnpm rebuild:sqlite`   | Rebuild SQLite native bindings                                 |\n| `pnpm create:migration` | Create new TypeORM migration                                   |\n\n## ⚙️ Configuration\n\nThe application uses YAML-based configuration with environment overrides:\n\n### Configuration Files\n\n- **`app-config.yaml`** - Main application configuration\n- **`app-config.local.yaml`** - Local development overrides\n- **`app-credentials.local.yaml`** - Local credentials (git-ignored)\n\n### Key Configuration Sections\n\n```yaml\napp:\n  name: \"sample-express-service\"\n  platform: \"node-boot\"\n  environment: \"development\"\n  port: 3000\n\napi:\n  routePrefix: \"/api\"\n  validations:\n    enableDebugMessages: true\n    stopAtFirstError: true\n\nserver:\n  cors:\n    origin: \"*\"\n    methods: [\"GET\", \"POST\"]\n```\n\n## 🏗️ Project Structure\n\n```\nsrc/\n├── app.ts                 # Main application class with decorators\n├── server.ts             # Application entry point\n├── auth/                 # Authentication \u0026 authorization\n├── clients/              # HTTP clients for external services\n├── config/               # Configuration classes\n├── controllers/          # REST API controllers\n├── exceptions/           # Custom exception handlers\n├── interfaces/           # TypeScript interfaces\n├── middlewares/          # Custom middleware\n├── models/               # DTOs and data models\n├── persistence/          # Database layer\n│   ├── entities/         # TypeORM entities\n│   ├── repositories/     # Custom repositories\n│   ├── migrations/       # Database migrations\n│   └── listeners/        # Entity event listeners\n└── services/             # Business logic services\n```\n\n## 🧩 Code Architecture\n\n### App Class\nMain application class with feature decorators:\n```typescript\n@EnableDI() // Enable Dependency Injection\n@EnableOpenApi() // Enable OpenAPI (Swagger) documentation\n@EnableSwaggerUI() // Enable SwaggerUI     \n@EnableAuthorization() // Enable Authorization\n@EnableActuator() // Enable Actuator (health, metrics)\n@EnableRepositories() // Enable persistence with TypeORM, transactions, migrations, listeners\n@EnableScheduling() // Enable scheduled tasks\n@EnableHttpClients() // Enable declarative HTTP clients\n@EnableValidations() // Enable request/response validations\n@EnableComponentScan() // Enable component scanning with AOT support\nexport class SampleApp implements NodeBootApp {\n    start(): Promise\u003cNodeBootAppView\u003e {\n        return NodeBoot.run(HttpServer);\n    }\n}\n```\n\n### Controllers\nREST API endpoints using decorators for routing and validation:\n\n```typescript\n@Controller(\"/users\", \"v1\")\nexport class UsersController {\n    @Get(\"/\")\n    async getUsers(): Promise\u003cUser[]\u003e {\n        return this.userService.findAllUser();\n    }\n}\n```\n\n**Key Features:**\n- Automatic route registration\n- Built-in validation\n- Swagger documentation generation\n- Exception handling\n\n### Services\nBusiness logic layer with dependency injection:\n\n```typescript\n@Service()\nexport class UserService {\n    constructor(\n        private readonly userRepository: UserRepository,\n        private readonly logger: Logger\n    ) {}\n}\n```\n\n**Key Features:**\n- Singleton instances\n- Constructor injection\n- Transaction support with `@Transactional`\n- Logging integration\n\n### Persistence Layer\n\n#### Entities\nTypeORM entities for database mapping:\n\n```typescript\n@Entity()\nexport class User {\n    @PrimaryGeneratedColumn()\n    id: number;\n    \n    @Column()\n    email: string;\n}\n```\n\n#### Repositories\nNode-Boot Data repositories extending TypeORM Repository:\n\n```typescript\n@DataRepository(User)\nexport class UserRepository extends Repository\u003cUser\u003e {\n    // Custom query methods\n}\n```\n\n**Key Features:**\n- Automatic transaction management\n- Custom naming strategies\n- Entity event listeners\n- Migration support\n\n### Models \u0026 DTOs\nData Transfer Objects with validation and OpenAPI metadata:\n\n```typescript\n@Model()\nexport class CreateUserDto {\n    @IsEmail()\n    email: string;\n    \n    @IsString()\n    @MinLength(8)\n    password: string;\n}\n```\n\n### Middlewares\nCustom middleware for cross-cutting concerns:\n\n- **`LoggingMiddleware`** - Request/response logging\n- **`CustomErrorHandler`** - Global error handling\n\n### Configuration Classes\nType-safe configuration with `@ConfigurationProperties`:\n\n```typescript\n@ConfigurationProperties(\"app\")\nexport class AppConfigProperties {\n    name: string;\n    port: number;\n    environment: string;\n}\n```\n\n## 🔧 Node-Boot Features Enabled\n\nThe application demonstrates various Node-Boot starters and features:\n\n| Feature              | Decorator              | Description                                   |\n|----------------------|------------------------|-----------------------------------------------|\n| Dependency Injection | `@EnableDI`            | TypeDI container integration                  |\n| OpenAPI              | `@EnableOpenApi`       | Automatic API documentation                   |\n| Swagger UI           | `@EnableSwaggerUI`     | Interactive API explorer                      |\n| Authorization        | `@EnableAuthorization` | Role-based access control                     |\n| Actuator             | `@EnableActuator`      | Health checks and metrics                     |\n| Persistence          | `@EnableRepositories`  | TypeORM integration + Transactions management |\n| Scheduling           | `@EnableScheduling`    | Cron jobs and scheduled tasks                 |\n| HTTP Clients         | `@EnableHttpClients`   | Declarative HTTP clients                      |\n| Validations          | `@EnableValidations`   | Request/response validation                   |\n| Component Scan       | `@EnableComponentScan` | AOT compilation support                       |\n\n## 🐛 Development\n\n### Hot Reload\nDevelopment server uses nodemon for automatic restarts:\n\n```json\n// nodemon.json\n{\n  \"watch\": [\"src\"],\n  \"ext\": \"ts,json,yaml\",\n  \"exec\": \"ts-node src/server.ts\"\n}\n```\n\n### Database\n- **Development:** SQLite database (`sample-database.db`)\n- **Migrations:** Use `pnpm create:migration` to create new migrations and then add the `@Migration` decorator to the generated migration class.\n- **Seeding:** Initial users loaded via `users.init.ts`\n\n## 🗄️ Database Configuration\n\n### Default Setup (SQLite)\nThe sample uses SQLite by default for simplicity and portability. The database file (`sample-database.db`) is created automatically in the project root.\n\n### Switching to Other Databases\n\nThe Node-Boot starter persistence package supports all TypeORM-compatible databases. You can easily switch by updating your configuration:\n\n#### Supported Databases\n- **SQL Databases:** PostgreSQL, MySQL, MariaDB, SQLite, Microsoft SQL Server, Oracle, CockroachDB\n- **NoSQL Databases:** MongoDB\n\n#### Configuration Steps\n\n1. **Install the appropriate database driver:**\n\n   ```bash\n   # PostgreSQL\n   pnpm add pg\n   pnpm add -D @types/pg\n\n   # MySQL/MariaDB\n   pnpm add mysql2\n\n   # MongoDB\n   pnpm add mongodb\n\n   # SQL Server\n   pnpm add mssql\n\n   # Oracle\n   pnpm add oracledb\n   ```\n\n2. **Update your configuration file (`app-config.yaml` or `app-config.local.yaml`):**\n\n   **SQLite Example (default):**\n   ```yaml\n   persistence:\n    type: \"better-sqlite3\"\n    synchronize: false # False, meaning that the application rely on migrations\n    cache: true\n    migrationsRun: true\n    better-sqlite3:\n        database: \"sample-database.db\"\n    transactions:\n        # Controls how many hooks (`commit`, `rollback`, `complete`) can be used simultaneously.\n        # If you exceed the number of hooks of same type, you get a warning. This is a useful to find possible memory leaks.\n        # You can set this options to `0` or `Infinity` to indicate an unlimited number of listeners.\n        maxHookHandlers: 10\n        # Controls storage driver used for providing persistency during the async request timespan.\n        # You can force any of the available drivers with this option.\n        # By default, the modern AsyncLocalStorage will be preferred, if it is supported by your runtime.\n        storageDriver: \"AUTO\"\n   ```\n   **PostgreSQL Example:**\n   ```yaml\n   persistence:\n     type: \"postgres\"\n     synchronize: false # False, meaning that the application rely on migrations\n     cache: true\n     migrationsRun: true\n     postgres:\n      host: \"localhost\"\n      port: 5432\n      username: \"your_username\"\n      password: \"your_password\"\n      database: \"your_database\"\n   ```\n\n   **MySQL Example:**\n   ```yaml\n   datasource:\n     type: \"mysql\"\n     synchronize: false # False, meaning that the application rely on migrations\n     cache: true\n     migrationsRun: true\n     mysql:\n      host: \"localhost\"\n      port: 3306\n      username: \"root\"\n      password: \"password\"\n      database: \"sample-database\"\n   ```\n\n   **MongoDB Example:**\n   ```yaml\n   persistence:\n    type: \"mongodb\"\n    cache: false\n    mongodb:\n      database: \"facts\"\n      #url: mongodb://localhost:27017/?directConnection=true\n      url: mongodb+srv://${DATABASE_CREDS}@db-name.mongodb.net/?retryWrites=true\u0026w=majority\u0026appName=sample-database\n   ```\n\n3. **Environment-specific Configuration:**\n   Use `app-config.local.yaml` for local development or `app-credentials.local.yaml` for sensitive credentials:\n\n   ```yaml\n   # app-credentials.local.yaml (git-ignored)\n   postgres:\n     username: \"your_username\"\n     password: \"your_password\"\n   ```\n\n#### Production Configuration\n\nFor production environments, use environment variables or secure configuration management:\n\n```yaml\nmysql:\n  username: \"${DB_USERNAME}\"\n  password: \"${DB_PASSWORD}\"\n  host: \"${DB_HOST:localhost}\"\n  port: \"${DB_PORT:5432}\"\n  database: \"${DB_NAME}\"\n```\n\n#### Database Features\n\nThe Node-Boot starter persistence package provides:\n\n- **Automatic Connection Management** - Connections are managed automatically\n- **Transaction Support** - Use `@Transactional` decorator for transaction management\n- **Migration System** - TypeORM migrations with Node-Boot decorators\n- **Entity Event Listeners** - Lifecycle hooks for entities\n- **Repository Pattern** - Custom repositories with `@DataRepository`\n- **Connection Pooling** - Built-in connection pool management\n\n#### Migration Commands\n\n```bash\n# Create new migration\npnpm create:migration\n```\n\u003e **Note:** After creating the migration class, add the `@Migration` decorator to the generated class to register it. Build and run the application to execute pending migrations at bootstrap.\n\n##### Example migration class:\n\n```typescript\nimport {MigrationInterface, QueryRunner} from \"typeorm\";\nimport {Migration} from \"@nodeboot/starter-persistence\";\n\n@Migration()\nexport class Migration1701786331338 implements MigrationInterface {\n   async up(queryRunner: QueryRunner): Promise\u003cvoid\u003e {\n      await queryRunner.query(`ALTER TABLE \"nb-user\" ADD COLUMN \"name\" varchar(255)`);\n   }\n\n   async down(queryRunner: QueryRunner): Promise\u003cvoid\u003e {\n      await queryRunner.query(`ALTER TABLE \"nb-user\" DROP COLUMN \"name\"`);\n   }\n}\n````\n\n#### Learn More\n\nFor detailed database configuration options, visit the [Node-Boot Starter Persistence](https://github.com/nodejs-boot/node-boot/tree/main/starters/persistence).\n\n### Testing\n- **Framework:** Jest with SWC compiler\n- **Configuration:** `jest.config.js`\n- **Run tests:** `pnpm test`\n\n### Code Quality\n- **Linting:** ESLint with TypeScript rules\n- **Formatting:** Prettier with import organization\n- **Type Checking:** Strict TypeScript configuration\n\n## 📁 Key Files\n\n- **`app.ts`** - Main application bootstrap with feature decorators\n- **`server.ts`** - Application entry point\n- **`package.json`** - Dependencies and scripts\n- **`tsconfig.json`** - TypeScript configuration\n- **`app-config.yaml`** - Application configuration\n- **`Dockerfile`** - Container configuration\n\n## 🚀 Production Deployment\n\n1. **Build the application:**\n   ```bash\n   pnpm build\n   ```\n\n2. **Start production server:**\n   ```bash\n   pnpm start:prod\n   ```\n\n3. **Docker deployment:**\n    * Build docker image\n   ```bash\n   docker build -f Dockerfile -t sample-express-service .\n   ```\n    * Run docker image\n   ```bash\n   docker run --rm -it -p 3000:3000 sample-express-service\n   ```\n    * Check container filesystem\n   ```bash\n   docker run -t -i sample-express-service /bin/sh\n   ```\n\n## API Explorer (Swagger UI)\nAccess the interactive API documentation at: [http://localhost:3000/docs](http://localhost:3000/docs)\n\n![swagger ui](assets/swagger-ui.png)\n\n## 📚 Learn More\n\n- [Node-Boot Documentation](https://github.com/nodejs-boot)\n- [Express Documentation](https://expressjs.com/)\n- [TypeORM Documentation](https://typeorm.io/)\n- [TypeDI Documentation](https://github.com/typestack/typedi)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodejs-boot%2Fsample-express","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnodejs-boot%2Fsample-express","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodejs-boot%2Fsample-express/lists"}