UNPKG

6.75 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`
126
127Runs backpack in development mode.
128
129Your code will reload if you make edits.
130You will see the build errors in the console that look like this.
131
132<img src="https://cloud.githubusercontent.com/assets/4060187/21944372/e2d5e556-d9a3-11e6-9842-0e01ce28ddd6.png" width="600" alt="backpack dev">
133
134### `backpack build`
135
136Builds the app for production to the `build` folder.
137It correctly bundles your production mode and optimizes the build for the best performance.
138
139You can run your production application with the following command:
140
141```bash
142node ./build/main.js
143```
144
145Your application is ready to be deployed!
146
147_Note: Make sure to add the `build` directory to your `.gitignore` to keep compiled code out of your git repository_
148
149## FAQ
150
151<details>
152 <summary>Is this like Create-React-App or Next.js?</summary>
153
154 Yes and No.
155
156Yes in that they will all make your life easier.
157
158No 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.
159
160</details>
161
162<details>
163 <summary>Can I use this with React to build a universal app?</summary>
164
165Technically, 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.
166</details>
167
168<details>
169 <summary>What syntactic features are transpiled? How do I change them?</summary>
170
171We 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.
172
173 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)
174</details>
175
176<details>
177 <summary>Why is it called Backpack?</summary>
178
179 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*.
180</details>
181
182## Inspiration
183
184* [jlongster/backend-with-webpack](https://github.com/jlongster/backend-with-webpack)
185* [nyt/kyt](https://github.com/NYTimes/kyt)
186* [zeit/next.js](https://github.com/zeit/next.js)
187* [facebookincubator/create-react-app](https://github.com/facebookincubator/create-react-app)
188
189## Authors
190
191* Jared Palmer ([@jaredpalmer](https://twitter.com/jaredpalmer)) - The Palmer Group
192
193---
194
195MIT License