Bun and JavaScript Tooling

Overview

The dev_tool integrates Bun as the JavaScript runtime and package manager for projects that include frontend or JavaScript tooling. Bun is used for installing dependencies, running scripts, building bundles, linting, formatting, type checking, and running tests.

Prerequisites

Local Mode

If your project uses local development mode, Bun must be installed on your host machine.

Windows (PowerShell):

irm bun.sh/install.ps1 | iex

Linux / macOS:

curl -fsSL https://bun.sh/install | bash

After installation, verify Bun is available:

bun --version

Containerized Mode

If your project uses containerized development mode, Bun is pre-installed inside the app container. No host installation is required. All Bun commands are executed inside the container via docker exec.

Configuration

pyproject.toml

Bun-specific settings are configured under the [tool.dev_tool.bun] section of your pyproject.toml:

[tool.dev_tool.bun]
test_directories = ["tests/js"]
source_directories = ["static/js"]

Field	Description	Default
test_directories	Directories containing JavaScript test files.	["tests/js"]
source_directories	Directories containing JavaScript source files.	["static/js"]

package.json

The dev_tool reads your project's package.json to determine which scripts are available. The following script names are recognized and used by the dev_tool:

Script	Purpose
build	Builds JavaScript bundles.
dev	Starts a file watcher for development (used by the Bun watcher runner).
format	Formats JavaScript/TypeScript code.
format:check	Checks formatting without making changes.
lint	Runs the linter.
lint:fix	Runs the linter with auto-fix.

If a script is not defined in package.json, the corresponding dev_tool command will display a warning and skip execution.

JavaScript Tab in the dev_tool

The JavaScript tab is available in the dev_tool only when containerized mode is enabled (containerized = true in pyproject.toml). This tab provides access to the following command groups:

Package Management

Command	Description
Install and upgrade all dependencies	Runs bun install to install all dependencies from package.json.
Install a dependency	Installs a single package (optionally as a dev dependency).
Uninstall a dependency	Removes a package using bun remove.
Check for outdated dependencies	Runs bun outdated to list outdated packages.
Upgrade all dependencies	Runs bun update to upgrade all packages.

Testing

Command	Description
Run tests	Runs JavaScript tests using bun test against configured test directories.
Run tests with coverage	Runs tests with the --coverage flag.
Run tests in watch mode	Runs tests with the --watch flag for continuous testing.

Code Quality

Command	Description
Lint	Runs the linter (requires a lint script in package.json).
Lint with auto-fix	Runs the linter with auto-fix (requires a lint:fix script in package.json).
Format code	Formats code (requires a format script in package.json).
Check formatting	Checks formatting without changes (requires a format:check script in package.json).

Bun Watcher

When a dev script is defined in package.json, the dev_tool can start a Bun watcher alongside the Django development server. The watcher monitors your JavaScript source files for changes and automatically rebuilds bundles.

In local mode, the watcher runs as a local process (bun run dev). In containerized mode, it runs inside the app container (docker exec -i <project>-app bun run dev).

Setting Up a New Project with Bun

1. Ensure your project is in containerized mode by setting containerized = true in pyproject.toml.

2. Create a package.json in the root of your project (or run bun init inside the container):

   {
       "name": "project-name",
       "scripts": {
           "build": "bun build ./static/js/index.js --outdir ./static/dist",
           "dev": "bun build ./static/js/index.js --outdir ./static/dist --watch"
       },
       "dependencies": {},
       "devDependencies": {}
   }
   

3. Add the Bun configuration to your pyproject.toml:

   [tool.dev_tool.bun]
   test_directories = ["tests/js"]
   source_directories = ["static/js"]
   

4. Start the dev_tool and navigate to the JavaScript tab to install dependencies and run scripts.

5. When running the Django development server, the Bun watcher will automatically start alongside it if a dev script is defined in package.json.