Tripack Minimal JavaScript Bundler

0.1.1 · active · verified Tue Apr 21

Tripack is a minimal JavaScript bundler, version 0.1.1, specifically designed for educational purposes rather than production use. It aims to demystify the core concepts behind modern bundlers like webpack and Rollup by implementing fundamental features from scratch. These features include AST parsing using `acorn`, building a comprehensive dependency graph, performing ESM to runtime-compatible transformations, and optionally executing export-level tree-shaking. The package emphasizes readability and simplicity in its codebase structure (e.g., `parser.ts`, `resolver.ts`, `treeshaker.ts`). While there's no explicit release cadence, its low version number suggests ad-hoc updates focused on clarity and concept demonstration. Its key differentiator is its role as a learning tool, providing a transparent view into bundling mechanics, unlike complex production-grade alternatives.

Common errors

```
Error: You must provide an entry file (--entry)
```
cause The `tripack` CLI was executed without specifying the required `--entry` argument, which points to the main JavaScript file to start bundling from.

fix When running `tripack` from the command line, always include `--entry <path/to/your/entry.js>` to specify your application's entry point.
```
Error: Node.js vX.Y.Z is not supported. tripack requires Node.js >= 20
```
cause The runtime Node.js version on the system is older than the minimum requirement specified by tripack (Node.js 20 or higher).

fix Update your Node.js installation to version 20 or later using a tool like `nvm` (Node Version Manager) or by downloading the latest LTS version from the official Node.js website.
```
Error: Cannot find module 'acorn' or 'acorn-walk'
```
cause The core dependencies `acorn` and `acorn-walk`, used for AST parsing, are not installed. This typically happens if `npm install` was not run in the project directory, or if the global `tripack` command cannot locate its dependencies.

fix If running `tripack` locally, ensure you've run `npm install` in the project root. If using a global install, `npm install -g tripack` should handle dependencies, but local issues can occur. Reinstalling globally might help: `npm install -g tripack`.

Warnings

gotcha Tripack is explicitly designed as an educational project and is not a full replacement for production-grade bundlers. It prioritizes readability and demonstrating core concepts over advanced optimizations, performance, or comprehensive feature sets.
Fix: For production applications, consider established bundlers like webpack, Rollup, or esbuild that offer robust features, optimizations, and community support.
gotcha The tree-shaking implementation in tripack is export-assignment based and intentionally conservative. It may not achieve the same level of dead code elimination as more sophisticated production bundlers.
Fix: Be aware that not all unused code might be eliminated. Review the bundled output if strict tree-shaking is critical for your use case. This limitation is by design for simplicity.
gotcha Tripack detects circular dependencies but does not block the bundling process; instead, it reports them. This can lead to unexpected runtime behavior or hard-to-debug issues if not addressed in the source code.
Fix: Identify and refactor your module dependencies to break circular references, as they can indicate architectural problems and complicate code comprehension and maintenance.

Install

npm install tripack npm
yarn add tripack yarn
pnpm add tripack pnpm

Imports

Bundler
wrong:
```
const Bundler = require('tripack');
```
correct:
```
import { Bundler } from 'tripack';
```
Tripack is primarily a CLI tool. While it ships TypeScript types and a `Bundler` class exists internally (`src/bundler.ts`), a direct programmatic API through the main package export (`import { Bundler } from 'tripack'`) is not explicitly documented as primary usage in v0.1.1. This is a speculative import for potential programmatic integration.
BundlerOptions
wrong:
```
import { BundlerOptions } from 'tripack';
```
correct:
```
import type { BundlerOptions } from 'tripack';
```
This type is likely used internally for configuring the bundler. If a programmatic API were exposed, `BundlerOptions` would define the structure for configuration. Use `import type` for type-only imports, especially in environments where type imports are tree-shaken.
Parser
wrong:
```
import { Parser } from 'tripack';
```
correct:
```
import { Parser } from 'tripack/dist/parser';
```
For a component like `Parser` (from `src/parser.ts`), direct access would typically require importing from a specific subpath, assuming `package.json` `exports` allow it, as it's not a top-level export. Programmatic usage of internal components like this is not officially documented for public consumption in v0.1.1.

Quickstart

This quickstart demonstrates how to install `tripack` globally and use its command-line interface to bundle a JavaScript entry file with optional tree-shaking into a single output file.

npm install -g tripack

# Assuming you have a project structure like:
# my-project/
#   src/index.js
#     console.log('Hello from index!');
#     import { foo } from './foo';
#     console.log(foo);
#   src/foo.js
#     export const foo = 'bar';

# Navigate to your project directory
# cd my-project

# Run tripack to bundle your entry file
tripack --entry src/index.js --out dist/bundle.js --tree-shake

# Verify the bundled output
node dist/bundle.js

# Expected output for the example above:
# Hello from index!
# bar

view raw JSON →