Powerlines: The Framework Framework

Common errors

• ERR_MODULE_NOT_FOUND: Cannot find package 'powerlines'

  cause The 'powerlines' package or one of its plugins is not installed.
  fix Run `pnpm add -D powerlines` (or `npm install -D powerlines`, `yarn add -D powerlines`) to install the core package. Also, ensure any specific `@powerlines/plugin-*` packages are installed if you are using them.

• TypeError: (0 , powerlines__WEBPACK_IMPORTED_MODULE_0__.definePowerlinesConfig) is not a function

  cause Attempting to use `definePowerlinesConfig` in a CommonJS context or with incorrect module resolution in a build tool, or a version mismatch where the function signature changed.
  fix Ensure your configuration file (`powerlines.config.ts`) is treated as an ESM module (e.g., using `type: 'module'` in `package.json` or configuring your bundler/TypeScript compiler accordingly). Verify the `powerlines` package version is compatible with your setup.

• Error: Peer dependency "X@Y" is not installed or incompatible

  cause A plugin for Powerlines requires a specific version of a build tool (e.g., `vite`, `esbuild`) that is either missing or does not meet the specified version range.
  fix Install the required peer dependency with the correct version. For example, if 'vite@^4.0.0' is required, run `pnpm add -D vite@latest` (or the specific compatible version).

Warnings

• gotcha Powerlines is explicitly stated to be in its 'initial development phase' where 'bugs and issues are expected.' It is not yet considered a 'proper release,' so exercise caution in production environments.
  Fix: Monitor GitHub issues and releases for stability improvements. Plan for potential breaking changes in minor versions. Report bugs to the developers.
• breaking The project uses `0.x.x` versioning, indicating that minor versions (`0.x.y` to `0.z.0`) may introduce breaking API changes without adhering to Semantic Versioning expectations for stable releases. Frequent updates mean rapid evolution.
  Fix: Always pin exact versions (`'powerlines': '0.x.y'`) rather than using ranges (`'^0.x.y'`). Thoroughly review release notes for each update to identify breaking changes and necessary code modifications.
• gotcha Powerlines has an extensive list of peer dependencies, requiring many build tools (e.g., Vite, Rollup, Webpack, esbuild, Nuxt, Astro) to be installed separately. Missing or incompatible peer dependencies can lead to runtime errors or unexpected behavior.
  Fix: Ensure all necessary peer dependencies for the specific plugins you use are explicitly installed in your project. Pay close attention to the version requirements listed in the `package.json` for compatibility.

Install

• npm install powerlines npm
• yarn add powerlines yarn
• pnpm add powerlines pnpm

Imports

• definePowerlinesConfig
  wrong:

  const { defineConfig } = require('powerlines')

  correct:

  import { definePowerlinesConfig } from 'powerlines'

  Used for defining Powerlines configuration in `powerlines.config.ts`. Primarily ESM-first.
• createPowerlines
  wrong:

  import Powerlines from 'powerlines'

  correct:

  import { createPowerlines } from 'powerlines'

  Main factory function to programmatically create a Powerlines instance. Destructured named import is standard.
• PowerlinesPlugin

  import type { PowerlinesPlugin } from 'powerlines'

  TypeScript type import for defining custom Powerlines plugins.

Quickstart

Demonstrates setting up `powerlines.config.ts` with `definePowerlinesConfig`, integrating Vite and esbuild plugins, and adding a custom plugin with basic hooks.

import { definePowerlinesConfig } from 'powerlines';
import { createVitePlugin } from '@powerlines/plugin-vite';
import { createEsbuildPlugin } from '@powerlines/plugin-esbuild';

export default definePowerlinesConfig({
  /**
   * Project-wide options for Powerlines.
   * For example, specifying where virtual modules should be resolved from.
   */
  output: {
    dir: './dist',
    clean: true
  },
  /**
   * Define your Powerlines plugins here.
   * These plugins can interact with various build tools.
   */
  plugins: [
    createVitePlugin({
      // Vite specific options
      optimizeDeps: {
        exclude: ['my-excluded-lib']
      }
    }),
    createEsbuildPlugin({
      // esbuild specific options
      target: 'es2022',
      minify: process.env.NODE_ENV === 'production'
    }),
    {
      name: 'my-custom-plugin',
      setup(powerlines) {
        // Example hook: Intercepting a build event
        powerlines.onBuildStart(() => {
          console.log('Custom plugin: Powerlines build started!');
        });
        // You can register virtual modules, transform code, etc.
      }
    }
  ],
  /**
   * Optional: Define global constants or environment variables
   * that Powerlines can inject into your builds.
   */
  define: {
    __APP_VERSION__: JSON.stringify('1.0.0'),
    __API_URL__: JSON.stringify(process.env.API_URL ?? 'http://localhost:3000')
  }
});