A pre-configured http server template that works with Bun.
- hono: web framework that is foundation of this template
- husky: commit checker that is being used with eslint and prettier in this project
- tsoa: helper that generates swagger definitions out of declarations in controllers
- prettier: code formatter for files that have extensions of ts, js and json files
- winston: a customizable logger for general usage
- zod: a schema validator
- eslint: identifier and reporter according to given patterns for js and ts files
To initiate a new repository using this template, simply click on the Use this template
button located at the top of the page. This will create a new repository with the contents of this template as the starting point.
Alternatively, if you prefer a manual installation process:
$ mkdir my-project
$ cd my-project
$ bun create icanvardar/bun-service-template
$ bun install
For those unfamiliar with Bun, please refer to the installation instructions for guidance..
- Linting and Formatting: Integrated linter (ESLint) and formatter (Prettier) to maintain consistent code quality and style.
- Git Hooks with Husky: Git hooks configured using Husky to automate checks and enforce code quality before commits.
- CI/CD with GitHub Actions: GitHub Actions workflow set up for continuous integration and deployment.
- Swagger Documentation: Utilizing TSOA to generate Swagger/OpenAPI definitions for API endpoints, hosted statically for easy access.
- Hono: Backend powered by Hono, ensuring efficient and scalable API handling.
- Test Suite with Jest: Comprehensive test suite located in the
tests
directory, integrated with Bun's built-in Jest for robust testing coverage. - Singleton Server Instance: Server instantiated as a singleton for optimized resource management.
- Environment Variables Handling: Zod used for parsing and validating environment variables, with support for multiple environments (development, production, test, CI).
- TypeScript Configuration: Well-structured
tsconfig.json
ensuring TypeScript compiler options are optimized for the project's needs. - Build Process: Build process handled using
Bun.build
for generating JavaScript output. - Declaration Files: Declaration files (
*.d.ts
) are supported, create and use anywhere in the project. - Custom TypeScript Plugin: Custom plugins for Bun's Build module, detailed in
plugins.ts
.
Default configurations can be found in these files, which you can adjust as you wish or according to your preferences.
├── .eslintignore
├── .eslintrc
├── .gitignore
├── .prettierignore
├── .prettierrc
├── build.mjs
├── bunfig.toml
├── tsconfig.json
└── tsoa.json
This template includes pre-configured GitHub Actions. It automatically runs linting and testing for your project whenever there's a push or pull request targeting the main
and issue-*
branches.
You have the flexibility to customize the CI script by editing the file .github/workflows/ci.yml.
Most Node.js-based projects use this kind of structure to manage different configurations for different environments. Bun enables automatic application of different settings in scenarios such as development, production, testing, and CI.
Firstly, you can define default configurations by creating a .env.example
file in the project root directory. Then, you can create files for each environment like .env.development
, .env.production
, .env.test
, where you specify the specific settings required for each environment.
Additionally, you can configure your project to automatically pull settings from the .env
folder if the NODE_ENV
value is empty. This can be used to check environment variables at the start of the project and load the appropriate .env
file.
For example, when creating a start
script:
"scripts": {
"start": "export NODE_ENV=production && bun run ./out/index.js",
"start:dev": "export NODE_ENV=development && bun index.ts",
"start:watch": "export NODE_ENV=development && bun --watch index.ts",
"test": "export NODE_ENV=test && bun test"
},
This assigns different NODE_ENV
values for different scenarios and automatically loads the .env
file.
In conclusion, by using this structure, you can seamlessly switch between different configurations when running your project in different environments (development, production, test), making it easier to manage.
You can use this template to create an OpenAPI document with tsoa and easily present it using Swagger UI. All you need to do is to configure your controllers using tsoa decorators to generate the controller logic in a way that will create the OpenAPI document.
Once you've completed the decorators, you can use the bun run generate:swagger
command to overwrite the Swagger definitions in the file named ./docs/swagger.json. After that, all you need to do is run the server. You can access Swagger UI via the /ui
route as specified in ./src/shared/server.ts
on line 72.
This approach makes it simple to generate and serve Swagger documentation for your API, providing an easy-to-use interface for exploring your API endpoints.
You can add a global variable in front of your HTTP server using basePath
. As seen in .env.example, you can update the BASE_PATH
value accordingly. For instance, if you have routes /foo
and /bar
on your server, and you're accessing them as localhost:3000/foo
and localhost:3000/bar
, you can add a base path to prefix all your routes.
For example, if you set the base path to /api
, your routes would become localhost:3000/api/foo
and localhost:3000/api/bar
.
If your project includes a base path and you want to generate Swagger using tsoa, you need to specify it like this: bun run generate:swagger --basePath /api
. Otherwise, your Swagger page won't display your route names correctly.
If you wish to write a new test, you can create files with extensions .test.ts
, .spec.ts
, or .t.ts
under the tests
directory located at the root of the project. You can write tests following the syntax of the Jest library. However, optionally, you can also use Chai.js and Mocha.js to write your tests, but for this, you'll need to install the libraries according to your customized setup beforehand.
To run tests, simply execute the command bun run test. If you want to generate test coverage, you should run bun run coverage
.
When conducting tests, the template automatically sets the NODE_ENV value to "test", allowing the compiler to read values from the .env.test
file. Please make sure to conduct your tests by modifying the .env.test
file accordingly.
This template includes an example test file ./tests/foo.spec.ts.
Here is a list of the most commonly used commands.
Build the project:
$ bun run build
Delete bun.lockb file, node_modules and build folder.
$ bun run clean
Start the project as development mode:
$ bun run start:dev
or for watch mode
$ bun run start:watch
Generate coverage report:
$ bun run coverage
Format the project files:
$ bun run format
Lint the project:
$ bun run lint
Run the tests:
$ bun run test
Generate test coverage and its result:
$ bun run coverage
This project is licensed under MIT.