Estrella Build Tool

Common errors

• Parameter 'ev' implicitly has an 'any' type. TS7006

  cause This TypeScript error indicates that a parameter's type could not be inferred and 'noImplicitAny' is enabled in your `tsconfig.json`.
  fix Estrella allows remapping TS diagnostic severities. Add a `tsrules` entry to your `build` options, e.g., `tsrules: { '7006': 'warn' }`, to treat this specific error as a warning instead of an error, or explicitly type the parameter (e.g., `ev: MouseEvent`).

• Error: Cannot find module 'estrella'

  cause The 'estrella' package is not installed or not resolvable from the current working directory.
  fix Run `npm install -D estrella` or `yarn add -D estrella` in your project's root directory. Ensure your build script is run from a location where `node_modules` is accessible.

Warnings

• breaking The API for the `watch` function underwent a breaking change in v1.4.0. Users explicitly calling `watch` directly should review the updated API documentation or examples.
  Fix: Consult the `estrella.d.ts` API documentation or `examples` directory for the correct `watch` function signature and usage patterns for versions 1.4.0 and later.
• gotcha Changes in internal handling of `define` entries within `BuildConfig` in v1.4.0 might subtly alter build behavior if relying on specific `define` configurations.
  Fix: Thoroughly test existing build configurations that use `define` options when upgrading to v1.4.0 or newer. Consult esbuild documentation for current `define` behavior.
• gotcha Behavior when `run`ning a program after building it might have changed in v1.4.1. This could affect scripts that automate execution post-build.
  Fix: Review the build script's `run` related logic and test its behavior when upgrading to v1.4.1 or later. Adjust program execution commands or `run` options as necessary.
• gotcha TypeScript diagnostics are optional and only run if a `tsconfig.json` file is present in the project directory or if `build({ tsc: true })` is explicitly set in the build script. Without these, only esbuild's basic transpilation occurs.
  Fix: To enable full TypeScript type checking and diagnostics, ensure a `tsconfig.json` is configured correctly, or add `tsc: true` to your `build` configuration object.

Install

• npm install estrella npm
• yarn add estrella yarn
• pnpm add estrella pnpm

Imports

• build
  wrong:

  const build = require('estrella')

  correct:

  import { build } from 'estrella'

  While CommonJS `require` is shown in examples, ESM `import` is the modern approach for modules. Both are supported for the main `build` function.
• watch
  wrong:

  build({ watch: true })

  correct:

  import { watch } from 'estrella'

  The `watch` function API changed in v1.4.0. Direct use of `watch` as a function should follow the updated API; previously, `build({ watch: true })` might have been sufficient for basic watching behavior.
• BuildConfig

  import type { BuildConfig } from 'estrella'

  Import types separately using `import type` for clarity and to avoid runtime overhead.

Quickstart

This quickstart demonstrates how to set up a basic build script using Estrella to compile a TypeScript entry point, bundle it, output it to a specified file, and explicitly enable TypeScript diagnostics.

#!/usr/bin/env node
const { build } = require("estrella")

// A basic build script compiling a TypeScript entry point
// and bundling it to a specified output file.
// TypeScript diagnostics are explicitly enabled.
build({
  entry: "src/main.ts",
  outfile: "out/foo.js",
  bundle: true,
  // Pass any options to esbuild here, e.g., minify, sourcemap, platform.
  // This also explicitly enables TypeScript diagnostics during the build.
  tsc: true
})

// To run this script: chmod +x build.js && ./build.js -watch