A Bun integration for Nest, made with Bun, for Bun runtime

Table of contents

• Description
• Project setup
• Compile & run the project
• Build the project
• Run tests
• Libraries Guides
  • 1. TypeORM
  • 2. Serving static files (@nestjs/serve-static)
• Support
• Stay in touch
• License

Description

The starter template for Nest with Bun runtime. This template utilizes the perks of Bun runtime & API to provide a seamless & performant development experience without taking away the familiarity of Nest & Node.js.

⚠️ Warning:

• This template is still in development and may not be suitable for production use. Please report any issues you encounter.
• Do NOT use Nest CLI with this template. A Nest-like, dedicated CLI tool for this template is currently in development.

Project setup

$ bun install

Compile & run the project

Bun can run TypeScript code directly, so there is no need to transpile the project before running it. At the same time, however, Bun will NOT perform any type-checking during development. Hence, tsc-watch & tsc is added to start scripts by default. Feel free to remove it if you want.

# development
$ bun run start

# watch mode
$ bun run start:dev

# production mode
$ bun run start:prod

Build the project

This template leverages a custom build script, located in scripts/build.ts, using Bun Build API to build the project. Feel free to modify the script to suit your needs.

$ bun run build # ⚠️ Be careful not to confuse this command with `bun build`.

The build output will be located in the dist folder, containing JS files. Unlike the default Nest template, the JS code inside the dist folder includes bundled dependencies, thanks to Bun. The result is that the server starts almost twice as fast as the default Nest template & the bun run start:dev script. You can run the built output directly with Bun using the following command:

$ bun run dist/main.js

However, using the bun run start:prod command is recommended, due to the NODE_ENV environment variable will be set to production.

Run tests

Bun is also a test runner and provides a Jest-like API for running tests. Hence, jest is not included in this template. You can run tests using the following commands:

# unit tests
$ bun run test

# e2e tests
$ bun run test:e2e

# test coverage
$ bun run test:cov

Libraries Guides

1. TypeORM

TypeORM can be used seamlessly with this template, just like any other Nest projects. However, by default, TypeORM CLI uses Node runtime, which requires you to install ts-node to execute TypeScript files. Therefore, using TypeORM CLI with Bun runtime is recommended, which can be achieved by passing the --bun flag like this:

# With bunx
$ bunx --bun typeorm <typeorm-command>

# Or with `bun run`, only if you have TypeORM installed as a dependency
$ bun run --bun typeorm <typeorm-command>

If you wish to transpile TypeORM's migrations to JS in order to use them in production, you can modify the build script (scripts/build.ts) to include the migration files:

1. Retrieve all the names of migration files, in this case, from the src/database/migrations folder, using Bun Glob API.

import { Glob } from 'bun';

const migrationFileNames = Array.from(
  new Glob('./src/database/migrations/*.ts').scanSync(),
).map((name) => name.replaceAll(/\\/g, '/'));

2. In the Bun.build function, add the migration files to the entrypoints array, and you are good to go:

import { build } from 'bun';

const result = await build({
  entrypoints: ['./src/main.ts', ...migrationFileNames],
  // ...

3. In order to execute TypeORM's CLI migration-related commands in production, you also have to specify the datasource config file in the entrypoints array:

const result = await build({
  entrypoints: [
    './src/main.ts',
    './src/database/migrations/ormconfig.ts', // Or path to your datasource config file
    ...migrationFileNames
  ],
  // ...

⚠️ Warning: While the entrypoint of the application is main.ts placed at src/ folder, if the migrations are NOT placed in the src/ folder, the build output main.js file will be placed at dist/src/, not dist/. The same goes for the datasource config file.

2. Serving static files (@nestjs/serve-static)

To serve static files in production, you must modify the build script to include them in the build output. There are two methods to achieve this:

Method 1. Specify the path to the static files in the entrypoints array:

import { Glob, build } from 'bun';

const staticFileNames = Array.from(
  new Glob('./src/static/*').scanSync(),
).map((name) => name.replaceAll(/\\/g, '/'));

const result = await build({
  entrypoints: ['./src/main.ts', ...staticFileNames],
  // ...

Just like the warning with TypeORM, if the static files (folder) are NOT placed in the src/ folder, the build output main.js file will be placed at dist/src/, not `dist/.

Method 2. Copy the static files to the build output folder using Bun Shell Scripting and the good old cp command:

import { $ } from 'bun';
import { join } from 'node:path';

await $`cp -R ${join(__dirname, '../src/static')} ${join(__dirname, '../dist/static')}`;

Using this method, you can place the static files (folder) anywhere you want.

Support

• Support Nest here.
• Contribute to Bun here.

Stay in touch

• Nest:

  • Author - Kamil Myśliwiec
  • Website - https://nestjs.com
  • Twitter - @nestframework

• Bun:

  • Author - oven-sh
  • Website - https://bun.sh
  • Twitter - @bunjavascript

• Me, the author of this template:

  • GitHub - @dung204
  • Twiter - @mantrilogix

License

• Nest is MIT licensed.
• Bun is MIT licensed
• This template is also MIT licensed.