jaredpalmer / Backpack

Backpack is minimalistic build system for Node.js. Inspired by Facebook's create-react-app, Zeit's Next.js, and Remy's Nodemon, Backpack lets you create modern Node.js apps and services with zero configuration. Backpack handles all the file-watching, live-reloading, transpiling, and bundling, so you don't have to. It comes with a few conventions defaults (like support for the latest JavaScript awesomeness (i.e. async/await, object rest spread, and class properties)), but everything can be customized to fit your project's needs. Best of all, you can easily add Backpack to your existing Node.js project with just a single dependency.

Backpack comes with the "battery-pack included":

• Latest ES6 features (including module syntax, async/await, object rest spread)
• SUPER friendly, human readable error messages
• Live reload (on saves, add/delete file, etc.)
• Zero-config, one dependency.

HOWEVER, you can configure Backpack to your project's needs by extending the underlying Webpack 4 configuration.

PLEASE READ: If you're thinking of using Backpack with React.js, you should use Razzle instead. It is a project purpose-built for SSR React with an almost identical API.

Table of Contents

• How to use
  • Custom configuration
  • Customizing webpack config
  • Customizing babel config
  • Building for Production
• CLI Commands
  • backpack dev
  • backpack build
• FAQ
• Inspiration
• Authors

How to use

Install it:

npm i backpack-core --save

and add a script to your package.json like this:

{
  "scripts": {
    "dev": "backpack"
  }
}

After that there are just a few conventions defaults:

• src/index.js: the entry of your app.

...actually that's it.

You can then run your application in development mode:

npm run dev

Successful builds will show a console like this. Note: screenshot taken from running the basic example

Custom configuration

For custom advanced behavior, you can create a backpack.config.js in the root of your project's directory (next to package.json).

// backpack.config.js
// IMPORTANT: This file is not going through babel transformation.
// You can however use the ES2015 features supported by your Node.js version.
module.exports = {
  /* config options here */
};

Customizing webpack config

Example

To extend webpack, you can define a function that extends its config via backpack.config.js.

// backpack.config.js
module.exports = {
  webpack: (config, options, webpack) => {
    // Perform customizations to config
    // Important: return the modified config
    return config;
  },
};

Customizing babel config

Example

To extend our usage of babel, you can define a .babelrc file at the root of your app. This file is optional.

If found, Backpack will consider it to be the source of truth. Thus it must define what Backpack needs as well, which is the backpack-core/babel preset.

This is designed so that you are not surprised by modifications we could make to the default babel configurations.

Here's an example .babelrc file:

{
  "presets": [
    "backpack-core/babel",
    "stage-0"
  ]
}

Note: This works exactly like Next.js does.

Building for Production

Add a npm script for the build step:

{
  "scripts": {
    "dev": "backpack",
    "build": "backpack build"
  }
}

Then run the build command and start your app

npm run build
node ./build/main.js

CLI Commands

backpack dev

Runs backpack in development mode.

Your code will reload if you make edits.
You will see the build errors in the console that look like this.

backpack build

Builds the app for production to the build folder.
It correctly bundles your production mode and optimizes the build for the best performance.

You can run your production application with the following command:

node ./build/main.js

Your application is ready to be deployed!

Note: Make sure to add the build directory to your .gitignore to keep compiled code out of your git repository

FAQ

Inspiration

• jlongster/backend-with-webpack
• nyt/kyt
• zeit/next.js
• facebookincubator/create-react-app

Authors

• Jared Palmer (@jaredpalmer) - The Palmer Group