Poops: Web Bundler and Static Site Generator

1.2.2 · active · verified Tue Apr 21

Poops is a straightforward, no-bullshit bundler and static site generator for web projects, currently stable at version 1.2.2. It leverages highly efficient tools like esbuild for JavaScript/TypeScript/JSX/TSX bundling and transpilation, and dart-sass for SCSS/SASS to CSS compilation. The package also integrates PostCSS for advanced CSS processing, including Tailwind CSS support, and offers design token integration (W3C DTCG & Style Dictionary). For static site generation, it supports swappable template engines, Nunjucks (default) or Liquid, with features for blogging, pagination, RSS/Atom/JSON feed generation, and React pre-rendering (Reactor). Poops prioritizes an intuitive, minimal-learning-curve approach, primarily driven by a simple JSON configuration file. Releases appear to be frequent, with minor versions rolling out new features and fixes every few weeks.

Common errors

```
SyntaxError: Cannot use import statement outside a module
```
cause Attempting to `require('poops')` or use CommonJS syntax after Poops migrated to ES modules in v1.1.0.

fix Change `require()` calls to `import` statements (e.g., `import { build } from 'poops';`) and ensure your Node.js environment or calling script supports ESM.
```
Error: Cannot find module 'postcss'
```
cause The `postcss` peer dependency is missing from your project.

fix Install `postcss`: `npm install postcss` or `yarn add postcss`.
```
Error: Config file not found at path: poops.json
```
cause The default configuration file `poops.json` (or `💩.json`) is missing from the project root, or a custom path was provided incorrectly.

fix Create `poops.json` or `💩.json` in your project's root, or ensure the custom config path passed to `npx poops` is correct.
```
Error: 'tailwindcss' is not found. Make sure it's installed and configured correctly.
```
cause Tailwind CSS is configured in `postcss` options but is not installed or incorrectly referenced.

fix Install Tailwind CSS (`npm install tailwindcss`) and ensure it's correctly listed in your PostCSS plugins array in `poops.json` and a `tailwind.config.js` exists if needed.

Warnings

breaking Version 1.1.0 migrated the entire codebase from CommonJS to ES modules. Any programmatic `require()` statements for Poops will break and must be updated to `import` syntax.
Fix: Update CommonJS `require()` calls to ES module `import` statements. Ensure your consuming project is configured for ESM (e.g., `"type": "module"` in package.json or using `.mjs` extensions).
gotcha Poops requires `postcss` as a peer dependency. If not installed, PostCSS features, including Tailwind CSS integration, will fail.
Fix: Install `postcss` alongside Poops: `npm install postcss` or `yarn add postcss`.
gotcha The configuration file for Poops must be named either `poops.json` or `💩.json` in the project root by default. Using other names requires specifying the path when running the command.
Fix: Ensure your configuration file is named `poops.json` or `💩.json` in the project root, or run `npx poops yourCustomConfig.json`.
gotcha When using the `markup` feature with template engines like Nunjucks or Liquid, ensure your template files and data structures align with the expected formats, especially for features like collections, pagination, and data loading from directories. Incorrect paths or data structures can lead to rendering issues.
Fix: Refer to the Poops documentation or examples for the correct structure of template files, data directories, and configuration for markup processing. Pay attention to how data is loaded and referenced within templates.

Install

npm install poops npm
yarn add poops yarn
pnpm add poops pnpm

Imports

build
wrong:
```
const { build } = require('poops');
```
correct:
```
import { build } from 'poops';
```
Poops migrated entirely to ES modules in v1.1.0. Programmatic usage must use ESM imports.
serve
wrong:
```
const { serve } = require('poops');
```
correct:
```
import { serve } from 'poops';
```
The `serve` function starts the local development server and rebuilds on file changes. ESM-only since v1.1.0.
CLI usage
wrong:
```
node poops.js
```
correct:
```
npx poops
```
While Poops can be installed globally (`npm i -g poops`), local installation and execution via `npx` is recommended for project-specific versions. The `💩` emoji is an alias for the `poops` command.

Quickstart

Demonstrates local installation, a basic `poops.json` configuration for bundling JavaScript, Sass, and Liquid templates, and how to execute the build command.

npm i -D poops

// poops.json in your project root
{
  "scripts": [
    {
      "in": "example/src/js/main.ts",
      "out": "example/dist/js/scripts.js",
      "options": {
        "sourcemap": true,
        "minify": true,
        "justMinified": false,
        "format": "iife",
        "target": "es2019"
      }
    }
  ],
  "styles": [
    {
      "in": "example/src/scss/main.scss",
      "out": "example/dist/css/styles.css",
      "options": {
        "sourcemap": true,
        "minify": true,
        "postcss": [
          "tailwindcss/nesting",
          "tailwindcss",
          "autoprefixer"
        ]
      }
    }
  ],
  "markup": [
    {
      "in": "example/src/markup/index.liquid",
      "out": "example/dist/index.html",
      "data": "example/src/data"
    }
  ]
}

// In your package.json scripts:
// "build": "npx poops"

// Run the build:
npx poops

view raw JSON →