Felt: On-demand ES6/CSS Bundler

Common errors

• Error: Cannot find module 'felt-recipe-minimal'

  cause The `felt-recipe-minimal` package (or another specified recipe) was not installed, or its path is incorrect.
  fix Install the required recipe: `npm install felt-recipe-minimal` or `npm install -g felt felt-recipe-minimal` if using the CLI globally.

• Error: listen EADDRINUSE: address already in use :::3000

  cause The default port 3000 (or a specified port) is already being used by another process on your system.
  fix Change the port Felt uses with the `--port` CLI option (e.g., `felt --port 3333`) or by setting the `port` option in your `felt.config.js`.

• ReferenceError: require is not defined (at file:///path/to/server.js:...) or SyntaxError: Cannot use import statement outside a module

  cause Attempting to use CommonJS `require()` in an ES module context or vice-versa, indicating a module system mismatch.
  fix Ensure your Node.js environment and file types are correctly configured for CommonJS (`.js` files without `"type": "module"` in package.json, or `.cjs` files) when using Felt, as it is a CommonJS library.

Warnings

• breaking Felt is a CommonJS-only package. Attempting to use `import` statements directly in an ES module environment will result in runtime errors. It predates widespread native ESM support in Node.js.
  Fix: Ensure your project or file where Felt is used operates in a CommonJS context (e.g., by using `.cjs` extension or `"type": "commonjs"` in package.json) and use `require()` syntax. If ESM is required, consider a CJS-to-ESM wrapper or alternative tooling.
• gotcha Felt itself does not bundle files out of the box; it requires 'recipes' (like `felt-recipe-minimal`) or custom `handlers` specified in its configuration to define how different file types (e.g., `.js`, `.css`) are processed.
  Fix: Always install a recipe (e.g., `npm install felt-recipe-minimal`) or define custom handlers in your `felt.config.js` file, ensuring all necessary bundler plugins (e.g., `felt-rollup`, `rollup-plugin-buble`) are also installed.
• gotcha Felt explicitly requires Node.js 6.x or above. While it may run on newer versions, its older dependencies (e.g., Rollup 0.x, Buble) might lead to compatibility issues or missing features compared to modern bundling setups.
  Fix: Ensure your Node.js environment is at least version 6.x. For newer Node.js versions, test thoroughly and be prepared for potential dependency conflicts or deprecation warnings related to older build tools.
• gotcha Felt's 'on-demand' bundling means assets are compiled dynamically upon request. This is great for development hot-reloading but can introduce latency for initial requests or heavy load in production environments compared to pre-compiled static assets.
  Fix: For production deployments, consider using Felt's `--export` option to pre-compile and serve static assets, or implement aggressive caching strategies on your server to mitigate compilation overhead.

Install

• npm install felt npm
• yarn add felt yarn
• pnpm add felt pnpm

Imports

• felt
  wrong:

  import felt from 'felt'

  correct:

  const felt = require('felt')

  Felt is a CommonJS module, primarily used with `require()`. There is no native ESM support.
• recipe
  wrong:

  import recipe from 'felt-recipe-minimal'

  correct:

  const recipe = require('felt-recipe-minimal')

  Recipes like `felt-recipe-minimal` are separate CommonJS modules that `felt` consumes. Do not use ES module `import` syntax.
• feltConfig
  wrong:

  import config from './felt.config.js'

  correct:

  const config = require('./felt.config.js')

  Configuration files are expected to be CommonJS modules exporting an object, typically required relative to the application's entry point.

Quickstart

Integrates Felt as an on-demand ES6/CSS bundler middleware with an Express.js server.

const express = require('express');
const felt = require('felt');
const path = require('path');
const config = require('./felt.config.js'); // Assuming felt.config.js exists and exports a Felt config object

const app = express();

// Integrate Felt as an on-demand bundling middleware
app.use(felt(config));

// Serve static files from the 'public' directory
app.use(express.static(path.join(__dirname, 'public')));

const PORT = process.env.PORT ?? 3000;
app.listen(PORT, () => {
  console.log(`Felt server running at http://localhost:${PORT}`);
  console.log('Serving static files from ./public and bundling JavaScript/CSS on-demand.');
});

// To set up:
// 1. npm install express felt felt-rollup rollup-plugin-buble rollup-plugin-node-resolve rollup-plugin-commonjs
// 2. Create 'felt.config.js' (as shown in the README example)
// 3. Create 'public/index.html' and 'public/main.js' (e.g., 'console.log("Hello from Felt!")')
// 4. Run with 'node server.js'