{"id":14956778,"url":"https://github.com/sidhantpanda/docker-express-typescript-boilerplate","last_synced_at":"2025-05-16T04:05:52.132Z","repository":{"id":37057844,"uuid":"181656496","full_name":"sidhantpanda/docker-express-typescript-boilerplate","owner":"sidhantpanda","description":"A dockerized TypeScript-Express App boilerplate with MongoDB and Github Actions","archived":false,"fork":false,"pushed_at":"2025-05-15T11:42:10.000Z","size":1563,"stargazers_count":313,"open_issues_count":25,"forks_count":95,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-05-15T12:36:29.556Z","etag":null,"topics":["actions","docker","eslint","express","hacktoberfest","jest","mongo","nodejs","swagger","typescript"],"latest_commit_sha":null,"homepage":"https://panda.fyi/projects/ts_express_boilerplate","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/sidhantpanda.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2019-04-16T09:19:21.000Z","updated_at":"2025-02-26T18:29:04.000Z","dependencies_parsed_at":"2024-01-15T06:31:35.739Z","dependency_job_id":"8913285f-521a-4154-9e8b-832f9dadb0ed","html_url":"https://github.com/sidhantpanda/docker-express-typescript-boilerplate","commit_stats":{"total_commits":397,"total_committers":6,"mean_commits":66.16666666666667,"dds":"0.32745591939546603","last_synced_commit":"4c7c5863c5e16799c9f59dd11032e1e58658b4fb"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidhantpanda%2Fdocker-express-typescript-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidhantpanda%2Fdocker-express-typescript-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidhantpanda%2Fdocker-express-typescript-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidhantpanda%2Fdocker-express-typescript-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sidhantpanda","download_url":"https://codeload.github.com/sidhantpanda/docker-express-typescript-boilerplate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254464895,"owners_count":22075570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["actions","docker","eslint","express","hacktoberfest","jest","mongo","nodejs","swagger","typescript"],"created_at":"2024-09-24T13:13:30.578Z","updated_at":"2025-05-16T04:05:47.122Z","avatar_url":"https://github.com/sidhantpanda.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca href=\"https://snyk.io//test/github/sidhantpanda/docker-express-typescript-boilerplate?targetFile=package.json\"\u003e\n  \u003cimg src=\"https://snyk.io//test/github/sidhantpanda/docker-express-typescript-boilerplate/badge.svg?targetFile=package.json\" alt=\"Known Vulnerabilities\" data-canonical-src=\"https://snyk.io//test/github/sidhantpanda/docker-express-typescript-boilerplate?targetFile=package.json\" style=\"max-width:100%;\"\u003e\n\u003c/a\u003e\n\u003ca href=\"#\"\u003e\n  \u003cimg src=\"https://github.com/sidhantpanda/docker-express-typescript-boilerplate/workflows/Publish%20latest%20image/badge.svg\" alt=\"Publish latest image\" style=\"max-width:100%;\"\u003e\n\u003c/a\u003e\n\n---\n\n# Express TypeScript Boilerplate with ChatGPT reviews\nThis repo can be used as a starting point for backend development with Nodejs. It comes bundled with Docker and is CI/CD optimized. The development environment uses `docker-compose` to start dependent services like mongo. There is [an action](https://github.com/sidhantpanda/docker-express-typescript-boilerplate/blob/master/.github/workflows/code-review.yml) to review all PRs with ChatGPT.\n\nA few things to note in the project:\n* **[Github Actions Workflows](https://github.com/sidhantpanda/docker-express-typescript-boilerplate/tree/master/.github/workflows)** - Pre-configured Github Actions to run automated builds and publish image to Github Packages.\n* **[Dockerfile](https://github.com/sidhantpanda/docker-express-typescript-boilerplate/blob/master/Dockerfile)** - Dockerfile to generate docker builds.\n* **[docker-compose](https://github.com/sidhantpanda/docker-express-typescript-boilerplate/blob/master/docker-compose.yml)** - Docker compose script to start service in production mode.\n* **[Containerized Mongo for development](#development)** - Starts a local mongo container with data persistence across runs.\n* **[Safe Mongooose Connection Helper](https://github.com/sidhantpanda/docker-express-typescript-boilerplate/blob/master/src/lib/safe-mongoose-connection.ts)** - A helper class to connect with Mongoose reliably.\n* **Joi** - For declarative payload validation\n* **[Middleware for easier async/await](https://github.com/sidhantpanda/docker-express-typescript-boilerplate/blob/master/src/middleware/request-middleware.ts)** - Catches errors from routes and throws them to express error handler to prevent app crash due to uncaught errors.\n* **[OpenAPI 3.0 Spec](https://github.com/sidhantpanda/docker-express-typescript-boilerplate/blob/master/openapi.yml)** - A starter template to get started with API documentation using OpenAPI 3.0. This API spec is also available when running the development server at `http://localhost:3000/dev/api-docs`\n* **[.env file for configuration](#environment)** - Change server config like app port, mongo url etc\n* **[Winston Logger](#logging)** - Uses winston as the logger for the application.\n* **ESLINT** - ESLINT is configured for linting.\n* **Jest** - Using Jest for running test cases\n\n## I. Installation\n\n### Using `curl`\n\n```\n$ bash \u003c(curl -s https://raw.githubusercontent.com/sidhantpanda/public/master/scripts/generate-express-ts-app.sh)\n```\n\n### Manual Method\n\n#### 1. Clone this repo\n\n```\n$ git clone git@github.com:sidhantpanda/docker-express-typescript-boilerplate.git your-app-name\n$ cd your-app-name\n```\n\n#### 2. Install dependencies\n\n```\n$ yarn install\n```\n\n## II. Configuration\n\n#### Update Docker repository for actions\n```\n$ yarn setup-actions\n```\n\n## III. Development\n\n### Start dev server\nStarting the dev server also starts MongoDB as a service in a docker container using the compose script at `docker-compose.dev.yml`.\n\n```\n$ yarn dev\n```\nRunning the above commands results in \n* 🌏**API Server** running at `http://localhost:3000`\n* ⚙️**Swagger UI** at `http://localhost:3000/dev/api-docs`\n* 🛢️**MongoDB** running at `mongodb://localhost:27017`\n\n## IV. Packaging and Deployment\n\nThe mongo container is only only available in dev environment. When you build and deploy the docker image, be sure to provide the correct **[environment variables](#environment)**.\n\n#### 1. Build and run without Docker\n\n```\n$ yarn build \u0026\u0026 yarn start\n```\n\n#### 2. Run with docker\n\n```\n$ docker build -t api-server .\n$ docker run -t -i \\\n      --env NODE_ENV=production \\\n      --env MONGO_URL=mongodb://host.docker.internal:27017/books \\\n      -p 3000:3000 \\\n      api-server\n```\n\n#### 3. Run with docker-compose\n\n```\n$ docker-compose up\n```\n\n\n---\n\n## Environment\nTo edit environment variables, create a file with name `.env` and copy the contents from `.env.default` to start with.\n\n| Var Name  | Type  | Default | Description  |\n|---|---|---|---|\n| NODE_ENV  | string  | `development` |API runtime environment. eg: `staging`  |\n|  PORT | number  | `3000` | Port to run the API server on |\n|  MONGO_URL | string  | `mongodb://localhost:27017/books` | URL for MongoDB |\n\n## Logging\nThe application uses [winston](https://github.com/winstonjs/winston) as the default logger. The configuration file is at `src/logger.ts`.\n* All logs are saved in `./logs` directory and at `/logs` in the docker container.\n* The `docker-compose` file has a volume attached to container to expose host directory to the container for writing logs.\n* Console messages are prettified\n* Each line in error log file is a stringified JSON.\n\n\n### Directory Structure\n\n```\n+-- scripts\n|   +-- dev.sh\n|   +-- setup-github-actions.sh\n+-- src\n|   +-- controllers\n|   |   +-- book\n|   |   |   +-- add.ts\n|   |   |   +-- all.ts\n|   |   |   +-- get.ts\n|   |   |   +-- index.ts\n|   |   |   +-- remove.ts\n|   |   |   +-- search.ts\n|   +-- errors\n|   |   +-- application-error.ts\n|   |   +-- bad-request.ts\n|   +-- lib\n|   |   +-- safe-mongo-connection.ts\n|   |   +-- winston-console-transport.ts\n|   +-- middleware\n|   |   +-- request-middleware.ts\n|   +-- models\n|   |   +-- Book.ts\n|   +-- public\n|   |   +-- index.html\n|   +-- app.ts\n|   +-- logger.ts\n|   +-- routes.ts\n|   +-- server.ts\n+-- .env.default\n+-- .eslintrc.json\n+-- .gitignore\n+-- .gitpod.yml\n+-- docker-compose.dev.yml\n+-- docker-compose.yml\n+-- Dockerfile\n+-- jest.config.js\n+-- LICENSE\n+-- nodemon.json\n+-- openapi.yml\n+-- package.json\n+-- README.md\n+-- renovate.json\n+-- tsconfig.json\n+-- yarn.lock\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsidhantpanda%2Fdocker-express-typescript-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsidhantpanda%2Fdocker-express-typescript-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsidhantpanda%2Fdocker-express-typescript-boilerplate/lists"}