package-json.md

Package.json Configuration for SmartBundle

This document outlines the required package.json configuration for SmartBundle and explains the rationale behind each constraint.

Overview

SmartBundle is a modern JavaScript bundler that enforces strict package.json configurations for reliable builds. Benefits include:

• Consistent ESM-to-CommonJS compatibility.
• Elimination of module resolution ambiguities.
• Prevention of accidental source code publishing.
• Automated generation of package.json for distribution.

This guide explains the required configuration and why certain constraints exist.

• Overview
• Banned Fields
• SmartBundle-specific Fields
• Exports

Banned Fields

Warning

The following fields must not be included in your source package.json as they conflict with SmartBundle’s automated handling.

files Field

SmartBundle calculates the import graph automatically and includes all necessary files. Using the 'files' field may result in missed dependencies or an overly bloated package.

main, module, browser, types Fields

These fields create ambiguity in module resolution. SmartBundle uses only the exports field for entry points, and the distributed package.json automatically includes the correct values, ensuring consistent behavior across environments.

SmartBundle-specific Fields

private Field

• Declaration: "private": true
• Requirement: This field must be set to true to prevent accidental publishing.

[!INFO]
When you run SmartBundle, it generates a new package.json in the output directory containing only the fields needed for publishing.

type Field

• Declaration: "type": "module"
• Requirement: SmartBundle only bundles ESM sources. Setting "type": "module" ensures that Node.js treats your .js files as ES modules, which is mandatory.

bin Field

• Declaration Example:

{
  "bin": {
    "my-command": "./src/bin.js"
  }
}

• Requirement: SmartBundle supports bin specifications (except for .sh files). If defined, they are processed to generate executable scripts for your package.
• For more details, see Node.js package.json bin specification.

Exports

The exports field defines the package’s entry points for SmartBundle’s ESM-only output. This field is automatically regenerated during bundling. It can be defined using either a simple string path or an object notation for subpath mappings.

Overview

• Declaration: "exports": "./src/index.js" (or object notation)
• Requirement: Defines the package entry point(s) that SmartBundle uses.
• "." key: Denotes the root address of the package.

Important

The "exports" field defines the entry points—and only the entry points—that SmartBundle uses.
During bundling, SmartBundle regenerates this field with the correct values for the output package.

For more information, see the Node.js Documentation: Package Exports.

Important

SmartBundle supports only direct string mappings in the exports field. Conditional keys (such as "import" or "require") and glob patterns (e.g. "**") are not supported.

Simple String Notation

Example – Simple String Notation:

{
  "exports": "./src/index.js"
}

Ensure that your ESM source file follows this format:

// ./src/index.js
export default function greet() {
  console.log('Hello, world!');
}
export function farewell() {
  console.log('Goodbye!');
}

Client Usage Examples:

• ESM Import:

import greet, { farewell } from 'your-package';
greet();
farewell();

• CommonJS Import:

const pkg = require('your-package');
pkg.default(); // for the default export
pkg.farewell();

Object Notation for Subpath Exports

Example – Object Notation for Subpath Exports:

{
  "exports": {
    ".": "./src/index.js",
    "./feature": "./src/feature/entrypoint.js"
  }
}

Usage Examples:

• Main Import (ESM):

import main from 'your-package';

• Feature Import (ESM):

import feature from 'your-package/feature';

For CommonJS, access the default export:

const mainPkg = require('your-package');
mainPkg.default();

For additional TypeScript-related setup and best practices, please refer to our TS Guide.