Config Reference

Poi will search poi.config.{ts,js} .poirc .poirc.json or poi property in package.json from your project.

The config is basically a pure object containing following properties.

module.exports = {
  // ...config

TypeScript is also supported if you're using the .ts extension:

import { Config } from 'poi'

const config: Config = {
  entry: 'src/index.js'

export default config

Be sure to install @types/poi and ts-node in your project first:

yarn add @types/poi ts-node typescript --dev
yarn poi --serve -r ts-node/register

You can access process.env.NODE_ENV in the config file, its default value is the same as CLI mode.


  • Type: string string[] object
  • Default: pkg.source || 'index'
  • CLI: poi [...entries]

Specify the entry file(s). It defaults to source file in your package.json and fallbacks to index when it's not present.

Note that the entres will be treated as files relative to current directory by default, if you want to use a npm package as entry, you need to prefix it with module:, like module:object.assign.



  • Type: string
  • Default: dist
  • CLI: -d, --out-dir <dir>

The directory to output files.


  • TypeL boolean
  • Default: true
  • CLI: --[no-]clean

Clean output directory before bundling.


  • Type: string
  • Default: iife
  • Values: iife cjs umd
  • CLI: --format <format>

Specify the output format.


  • Type: string
  • CLI: --module-name <name>

Specify the output module name for bundles in umd format.


  • Type: boolean
  • Default: false in production mode, true otherwise
  • CLI: --[no-]source-map

Generate source map.


  • Type: boolean
  • Default: true in production mode, false otherwise
  • CLI: --[no-]minimize

Minimize output files.


  • Type: string
  • Default: '/'
  • CLI: --public-url <url>

The base URL your application bundle will be deployed at. This is the equivalent of webpack's output.publicPath, but Poi also needs this value for other purposes, so you should always use this instead of modifying webpack output.publicPath.


  • Type: FileNames
  • Default: DefaultFileNames
interface FileNames {
  js?: string
  css?: string
  font?: string
  image?: string

// In `iife` output format
const DefaultFileNames = {
  js: isProduction
    ? 'assets/js/[name].[chunkhash:8].js'
    : 'assets/js/[name].js',
  css: isProduction
    ? 'assets/css/[name].[chunkhash:8].css'
    : 'assets/css/[name].css',
  font: isProduction
    ? 'assets/fonts/[path][name].[hash:8].[ext]'
    : 'assets/fonts/[path][name].[ext]',
  image: isProduction
    ? 'assets/images/[path][name].[hash:8].[ext]'
    : 'assets/images/[path][name].[ext]'

// In `cjs` `umd` output format
const DefaultFileNames = {
  js: '[name].js',
  css: '[name].css',
  font: '[path][name].[ext]',
  image: '[path][name].[ext]'

  • Type: 'web' | 'electron-renderer' | 'electron-main' | 'node' | 'node-webkit' | 'async-node' | 'webworker'
  • Default: 'web'
  • CLI: --target <target>

Bundle target.


Customize generated HTML file. This is only available in iife and umd format.

The options you provide here will also be available under html variable in your HTML file, so you can access them using EJS syntax:

<title><%= html.title %></title>


  • Type: string
  • Default: pkg.productName || || 'Poi App'
  • CLI: --html.title <title>

Document title.


  • Type: string
  • Default: index.html
  • CLI: --html.filename <filename>

The filename of generated HTML file.


  • Type: string
  • Default: poi/lib/webpack/default-template.html
  • CLI: --html.template <template>

The template file for generated HTML file, supporting EJS syntax.


  • Type: boolean
  • Default: true
  • CLI: --[no-]html.inject

Automatically inject webpack assets to <head> and <body>.


Build the app in multi-page mode. Each "page" should have a corresponding JavaScript entry file. The value should be an object where the key is the name of the entry, and the value is either:

  • An object that specifies its entry, template, filename, title and chunks (all optional except entry). Any other properties added beside those will also be passed directly to html-webpack-plugin, allowing user to customize the plugin.
  • Or a string specifying its entry.
module.exports = {
  pages: {
    // Generate index.html using specified entry
    index: './src/index.js',
    // Generate foo.html
    foo: {
      entry: './src/foo.js',
      // chunks to include on this page, by default includes
      // extracted common chunks, vendor chunks and itself
      chunks: ['chunk-vendors', 'chunk-common', 'foo']
      // ...other options

When using this option, entry and output.html will no longer take effects.



  • Type: string
  • Default: react
  • Values: react preact vue h or any JSX pragma
  • CLI: --jsx <jsx>

Set JSX syntax. This ONLY works with our default Babel preset, which means it won't work if you're using custom Babel config file like babel.config.js.


  • Type: Array<string | RegExp>

Transpile specific modules in Babel transpilation process. By default Babel only transpiles files outside node_modules directory.


  • Type: boolean
  • CLI: --no-babelrc

Enable or disable .babelrc files.


  • Type: boolean
  • CLI: --no-babel-config-file

Enable or disable babel.config.js.



  • Type: boolean
  • Default: true in production builds, false otherwise
  • CLI: --[no-]extract-css

Whether to extract CSS into standalone CSS files.


Whether to enable source map for CSS files.


  • Type: LoaderOptions

Specify the options for CSS loaders.

interface LoaderOptions {
  // css-loader
  css?: any
  // sass-loader
  sass?: any
  // postcss-loader
  postcss?: any
  // less-loader
  less?: any
  // stylus-loader
  stylus?: any



  • Type: number
  • Default: 5000 (bytes)

Images that are smaller than this size will be inlined in the bundle.


Embed environment variables into your app code.

See details


Replace global constants in your app code with the value you defined here:

module.exports = {
  constants: {
    FOO: 'bar'

Then in your app code:

let FOO = 123

Transpiled code:

let bar = 123


  • Type: boolean
  • CLI: --react-refresh

Enable React Refresh


  • Type: (config: WebpackChain, opts: Opts) => void

Modify internal webpack config with the webpack-chain API.

interface Opts {
  /** Default: client */
  type: string
  [k: string]: any

// Some plugin might supply custom opts for creating customized webpack config
// e.g. creating one for client bundle and the other one for server bundle


  • Type: WebpackConfig | ((config: WebpackConfig, opts: Opts) => WebpackConfig | void)

Instead of using chainWebpack you can provide an object or a function as the value of configureWebpack option:

module.exports = {
  chainWebpack(config) {
    // optionally `return config`

  // or object
  // merged using `webpack-merge` module
  configureWebpack: {
    resolve: {
      extensions: ['.mdx']

When using an object, it's merged with our internal webpack config by webpack-merge.


  • Type: string boolean
  • Default: public

Serve static file in this folder. Use false to disable this behavior.


  • Type: string
  • Default:
  • CLI: --host <host>

Server host.


  • Type: string number
  • Default: 4000
  • CLI: --port <port>

Server port.

  • Type: boolean
  • Default: true

Enables Hot Module Replacement.


  • Type: boolean
  • Default: false

Enables Hot Module Replacement (see without page refresh as fallback in case of build failures.


  • Type: string[]
  • Default: []

Make specific webpack entries hot-reloadable, by default Poi will make all entries hot-reloadable.


  • Type: boolean object
  • Default: true

When using the HTML5 History API, the index.html page will likely have to be served in place of any 404 responses. devServer.historyApiFallback is enable by default. Disable it by passing false here. By passing an object this behavior can be controlled further using options like rewrites. Check webpack-dev-server documentation for more information.

  • Type: boolean
  • Default: false
  • CLI: -o, --open

Open the dev server in your browser when bundle succeeded.


  • Type: string object function
  • CLI: --proxy <string>

See Proxying API Requests.


  • Type: boolean object


  • Type: (app: Express) => void

Execute a function before our middlewares.


  • Type: (app: Express) => void

Execute a function after our middlewares.


  • Type: object

Set custom headers on all responses.


  • Type: string[] | { resolve: string, options?: any }[]

An array of plugins.

Last Updated: 8/21/2020, 4:01:51 PM