Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cli
✓ npx poi --serve
✗ import { serve } from 'poi'
Poi is primarily a CLI tool. Direct programmatic imports for bundling operations are uncommon for end-users. Configuration is handled via `poi.config.js`.
poi.config.js
✓ module.exports = { entry: './src/index.js', plugins: [ require('@poi/plugin-vue')() ] };
Poi's configuration is typically defined in a `poi.config.js` file using CommonJS `module.exports`. This file allows for custom entry points, plugins, and other Webpack-level adjustments.
This quickstart demonstrates how to set up a new project with Poi, create a simple JavaScript and CSS entry point, and use the built-in development server and build command.
mkdir my-poi-app
cd my-poi-app
npm init -y
npm install --save-dev poi
# Create an entry file, e.g., src/index.js
mkdir src
cat > src/index.js <<EOF
import './style.css';
const app = document.createElement('div');
app.id = 'app';
app.textContent = 'Hello from Poi!';
document.body.appendChild(app);
console.log('Poi is running!');
EOF
# Create a basic CSS file, e.g., src/style.css
cat > src/style.css <<EOF
body {
font-family: sans-serif;
display: flex;
justify-content: center;
align-items: center;
min-height: 100vh;
margin: 0;
background-color: #f0f0f0;
}
#app {
padding: 20px;
background-color: white;
border-radius: 8px;
box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
}
EOF
# Add 'dev' and 'build' scripts to package.json
npm set-script dev "poi --serve src/index.js"
npm set-script build "poi --prod src/index.js"
# Run the development server
npm run dev
poi --version
Debug
Known issues
breakingPoi has been officially deprecated. The project is no longer actively maintained, and users are strongly advised to migrate to modern bundlers like Vite for new and existing projects.fixMigrate your project to an actively maintained bundler such as Vite (recommended by Poi's maintainer), Parcel, or Webpack. Evaluate migration guides provided by those tools.
affects: >=12.10.4 (effectively all versions due to deprecation)
gotchaAs a deprecated tool, Poi may not be compatible with newer versions of Node.js or updated dependencies, potentially leading to build failures or unexpected behavior.fixIf bound to Poi, consider pinning Node.js and dependency versions to those known to be compatible with its last release (v12.10.3, released Oct 2020), or migrate to a modern bundler.
affects: >=12.10.3 with newer Node.js/dependencies
Errors
Common errors & fixes
Error: Cannot find module 'module-name'
A required module or dependency specified in your code or a preset configuration cannot be resolved by the bundler.
fixEnsure all necessary dependencies are installed (`npm install` or `yarn install`). Verify import paths and module names in your code and `poi.config.js`.
Error: Unexpected token '...'
This error often occurs when modern JavaScript syntax (e.g., spread syntax, optional chaining) is used but the configured Babel (or similar transpiler) preset within Poi does not support it, or is missing.
fixEnsure you have the correct `@poi/plugin-babel` or `poi-preset-typescript` (if using TypeScript) installed and configured in your `poi.config.js` to handle modern syntax or target the appropriate ECMAScript version.
Build fails without clear error messages, or development server doesn't start.
This can often be due to incompatibility with newer Node.js versions, breaking changes in underlying Webpack versions (which Poi abstracts), or missing plugins for specific file types.
fixCheck the `poi` CLI output for any warnings, even if the process doesn't explicitly 'error'. Try running with `--no-progress` or `--verbose` for more detailed output. Consult community forums or migrate to a more current bundler if the issue persists with newer environments.
Audit
Dependencies
webpackrequiredPoi is built on top of Webpack to perform its bundling operations.
create-poi-appoptionalUsed for quick project scaffolding.
poi-preset-*optionalExtended functionality for specific frameworks (e.g., React, Vue, TypeScript) or tools (e.g., ESLint, Bundle Analyzer) through official presets.