UNPKG

6.74 kBMarkdownView Raw
1![backpack](https://cloud.githubusercontent.com/assets/4060187/21872211/318795e8-d835-11e6-8376-bea370605361.png)
2
3![backpack-status](https://david-dm.org/palmerhq/backpack.svg?path=packages/backpack-core)
4[![npm version](https://badge.fury.io/js/backpack-core.svg)](https://badge.fury.io/js/backpack-core) [![Join the chat at https://gitter.im/palmerhq/backpack](https://badges.gitter.im/palmerhq/backpack.svg)](https://gitter.im/palmerhq/backpack?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
5
6Backpack is minimalistic build system for Node.js. Inspired by Facebook's [create-react-app](https://github.com/facebookincubator/create-react-app), Zeit's [Next.js](https://github.com/zeit/next.js), and Remy's [Nodemon](https://github.com/remy/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.
7
8**Backpack comes with the "battery-pack included":**
9
10- Latest ES6 features (including module syntax, async/await, object rest spread)
11- SUPER friendly, human readable error messages
12- Live reload (on saves, add/delete file, etc.)
13- Zero-config, one dependency.
14
15HOWEVER, you can configure Backpack to your project's needs by extending [the underlying Webpack 2 configuration](#custom-configuration).
16
17## How to use
18
19Install it:
20
21```bash
22npm i backpack-core --save
23```
24
25and add a script to your package.json like this:
26
27```json
28{
29 "scripts": {
30 "dev": "backpack"
31 }
32}
33```
34
35After that there are just a few ~~conventions~~ defaults:
36
37- `src/index.js`: the entry of your app.
38
39...actually that's it.
40
41You can then run your application in development mode:
42
43```bash
44npm run dev
45```
46
47Successful builds will show a console like this. *Note: screenshot taken from running the [basic example](https://github.com/palmerhq/backpack/tree/master/examples/basic)*
48<img src="https://cloud.githubusercontent.com/assets/4060187/21944379/eaba2fde-d9a3-11e6-87aa-f30ddc88b5a8.png" width="600" alt="npm run dev">
49
50### Custom configuration
51
52For custom advanced behavior, you can create a `backpack.config.js` in the root of your project's directory (next to `package.json`).
53
54```js
55// backpack.config.js
56// IMPORTANT: This file is not going through babel transformation.
57// You can however use the ES2015 features supported by your Node.js version.
58module.exports = {
59 /* config options here */
60}
61```
62
63### Customizing webpack config
64
65[Example](https://github.com/palmerhq/backpack/tree/master/examples/with-custom-webpack-config)
66
67To extend webpack, you can define a function that extends its config via `backpack.config.js`.
68
69```js
70// backpack.config.js
71module.exports = {
72 webpack: (config, options, webpack) => {
73 // Perform customizations to config
74 // Important: return the modified config
75 return config
76 }
77}
78```
79
80### Customizing babel config
81
82[Example](https://github.com/palmerhq/backpack/tree/master/examples/with-custom-babel-config)
83
84To extend our usage of `babel`, you can define a `.babelrc` file at the root of your app. This file is optional.
85
86If 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.
87
88This is designed so that you are not surprised by modifications we could make to the default `babel` configurations.
89
90Here's an example `.babelrc` file:
91
92```js
93{
94 "presets": [
95 "backpack-core",
96 "stage-0"
97 ],
98}
99```
100
101*Note: This works [exactly like Next.js does](https://github.com/zeit/next.js#customizing-babel-config).*
102
103### Building for Production
104
105Add a npm script for the build step:
106
107```json
108{
109 "scripts": {
110 "dev": "backpack",
111 "build": "backpack build"
112 }
113}
114```
115
116Then run the build command and start your app
117
118```bash
119npm run build
120node ./build/main.js
121```
122
123## CLI Commands
124
125### `backpack dev`
126Runs backpack in development mode.
127
128Your code will reload if you make edits.
129You will see the build errors in the console that look like this.
130
131<img src="https://cloud.githubusercontent.com/assets/4060187/21944372/e2d5e556-d9a3-11e6-9842-0e01ce28ddd6.png" width="600" alt="backpack dev">
132
133### `backpack build`
134Builds the app for production to the `build` folder.
135It correctly bundles your production mode and optimizes the build for the best performance.
136
137You can run your production application with the following command:
138
139```bash
140node ./build/main.js
141```
142
143Your application is ready to be deployed!
144
145*Note: Make sure to add the `build` directory to your `.gitignore` to keep compiled code out of your git repository*
146## FAQ
147
148<details>
149 <summary>Is this like Create-React-App or Next.js?</summary>
150
151 Yes and No.
152
153Yes in that they will all make your life easier.
154
155No in that it that Backpack is focused on server-only applications. You should use create-react-app or Next.js for your frontend and then build your backend with Backpack.
156</details>
157
158<details>
159 <summary>Can I use this with React to build a universal app?</summary>
160
161Technically, yes. However, we strongly advise against it at the moment. Backpack handles file-watching and reloading in a way that will make things like webpack-hot-middleware annoying to work with.
162</details>
163
164<details>
165 <summary>What syntactic features are transpiled? How do I change them?</summary>
166
167We track V8. Since V8 has wide support for ES6 and async and await, we transpile those. Since V8 doesn’t support class decorators, we don’t transpile those.
168
169 See [this](https://github.com/palmerhq/backpack/blob/master/packages/backpack-core/config/webpack.config.js#L83) and [this](https://github.com/palmerhq/backpack#customizing-webpack)
170</details>
171
172<details>
173 <summary>Why is it called Backpack?</summary>
174
175 Backpack is focused on server-only applications. We've been using it for building out Node.js backends and microservices. Under the hood, Webpack and a few other tools make the magic happen. Hence Backend + Webpack = *Backpack*.
176</details>
177
178## Inspiration
179- [jlongster/backend-with-webpack](https://github.com/jlongster/backend-with-webpack)
180- [nyt/kyt](https://github.com/NYTimes/kyt)
181- [zeit/next.js](https://github.com/zeit/next.js)
182- [facebookincubator/create-react-app](https://github.com/facebookincubator/create-react-app)
183
184## Authors
185
186- Jared Palmer ([@jaredpalmer](https://twitter.com/jaredpalmer)) - The Palmer Group