2 |
3 | # webpack-starter-basic
4 | [](http://forthebadge.com)[](http://forthebadge.com)
5 |
6 | [](https://david-dm.org/lifenautjoe/webpack-starter-basic)
7 |
8 | A simple **webpack 4 starter project** for your basic web development needs.
9 |
10 | Read more on the [demo website](https://lifenautjoe.github.io/webpack-starter-basic/) or continue reading below.
11 |
12 | ## Table of Contents
13 |
14 | - [Motivation](#motivation)
15 | - [Features](#features)
16 | - [Requirements](#requirements)
17 | - [Usage](#usage)
18 | - [FAQ](#faq)
19 | * [When should I use this starter?](#when-should-i-use-this-starter)
20 | * [Where's the common webpack config?](#wheres-the-common-webpack-config)
21 | * [How to load fonts](#how-to-load-fonts)
22 | * [How to load images](#how-to-load-images)
23 | + [In JavaScript](#in-javascript)
24 | + [In `index.html`](#in-indexhtml)
25 | * [How to install bootstrap 4](#how-to-install-bootstrap-4)
26 | - [Websites using this starter kit on the wild](#websites-using-this-starter-kit-on-the-wild)
27 |
28 | ## Motivation
29 |
30 | I needed to make a plain ol' "drop your mail to stay updated of ongoing developments" page.
31 |
32 | I did not need anything fancy, no frontend framework, no unit testing, simply a **starter project that would let me use sass, ES6, load assets, add vendor prefixes, start a dev server, generate sourcemaps and optimize everything for production.**
33 |
34 | I looked around and all I found were heavily specialized and complicated webpack starter projects (`webpack-angular-starter`, `webpack-react-starter`, etc) that are so intertwined with plugins that stripping undesired functionality is almost impossible.
35 |
36 | So I did this.
37 |
38 | ## Features
39 |
40 | * Separated development and production webpack settings you can understand
41 | * Sass
42 | * ES6
43 | * Asset loading
44 | * CSS Vendor prefixing
45 | * Development server
46 | * Sourcemaps
47 | * Favicons generation
48 | * Production optimizations
49 | * Mobile browser header color
50 |
51 | ## Requirements
52 |
53 | * [Node](https://nodejs.org) > 7.6
54 |
55 | ## Usage
56 |
57 | Substitute `PROJECT-NAME` for your project name.
58 |
59 | Clone the repository
60 |
61 | ```sh
62 | git clone https://github.com/lifenautjoe/webpack-starter-basic PROJECT-NAME
63 | cd PROJECT-NAME
64 | ```
65 |
66 | Install npm dependencies
67 |
68 | ```sh
69 | npm install
70 | ```
71 |
72 | Run the kickstart command
73 | ```sh
74 | npm run kickstart
75 | ```
76 |
77 | **After the project has been kickstarted**
78 |
79 | To start the development server
80 |
81 | ```sh
82 | npm start
83 | ```
84 |
85 | To build for production
86 |
87 | ```sh
88 | npm run build
89 | ```
90 |
91 | To preview the production build
92 | ```sh
93 | npm run preview
94 | ```
95 |
96 | ## FAQ
97 |
98 | ### When should I use this starter?
99 |
100 | You should use this starter if any of the following are true:
101 |
102 | * You want to make a static page. e.g. splash screen, onboarding screen, phaser game, threejs visualization, countdown.
103 | * You found no good starter kit for whatever you want to do and need a solid place to start from.
104 |
105 | **Please note**: If you are going to use a frontend framework like angular or react, you can of course add the required plugins and
106 | configuration but it's normally complicated and quirky enough that it's highly recommended to use one of the existing
107 | starter projects such as [react-webpack-babel](https://github.com/alicoding/react-webpack-babel) or for angular projects the [angular-cli](https://github.com/angular/angular-cli).
108 |
109 | ### Where's the common webpack config?
110 |
111 | **There is none and that is good thing.**
112 |
113 | The pattern creates unnecessary confusion over the setup, at the end the config will always be different across environments.
114 | People just put booleans everywhere on the common config to switch between these differing configuration options which is just awful to see and confusing for someone who's just starting on webpack.
115 |
116 | The only truly shared config between these files are the entry js point and the main html template.
117 |
118 | ### How to load fonts
119 |
120 | If you don't support Opera Mini, browsers support the .woff format. Its newer version .woff2, is widely supported by modern browsers and can be a good alternative.
121 |
122 | If you decide to use only this format you can load the fonts in a similar manner to images.
123 |
124 | In your `webpack.dev.js` and `webpack.prod.js` add the following
125 |
126 | ```js
127 | module.exports = {
128 | // ..
129 | module: {
130 | rules: [
131 | // ..
132 | {
133 | test: /\.woff$/,
134 | loader: 'url-loader',
135 | options: {
136 | // Limit at 50k. Above that it emits separate files
137 | limit: 50000,
138 | // url-loader sets mimetype if it's passed.
139 | // Without this it derives it from the file extension
140 | mimetype: 'application/font-woff',
141 | // Output below fonts directory
142 | name: './fonts/[name].[ext]',
143 | },
144 | }
145 | // ..
146 | ]
147 | }
148 | // ..
149 | };
150 | ```
151 |
152 | And let's say your font is in the folder `assets` with the name `pixel.woff`
153 |
154 | You can add it and use it in `index.scss` as
155 | ```scss
156 | @font-face {
157 | font-family: "Pixel";
158 | src: url('./../assets/pixel.woff') format('woff');
159 | }
160 |
161 | .body{
162 | font-family: 'Pixel', sans-serif;
163 | }
164 | ```
165 |
166 | If you would like to support all kinds of font types, remove the woff rule we previously added to `webpack.dev.js` and `webpack.prod.js` and add the following
167 |
168 | ```js
169 | module.exports = {
170 | // ..
171 | module: {
172 | rules: [
173 | // ..
174 | {
175 | test: /\.(ttf|eot|woff|woff2)$/,
176 | loader: 'file-loader',
177 | options: {
178 | name: 'fonts/[name].[ext]',
179 | },
180 | }
181 | // ..
182 | ]
183 | }
184 | // ..
185 | };
186 | ```
187 |
188 | And assuming you have your fonts in the directory `assets` with names `pixel.woff`, `pixel.ttf`, `pixel.eot` , etc.
189 |
190 | You can add it and use it in `index.scss` as
191 | ```scss
192 | @font-face {
193 | font-family: 'Pixel';
194 | src: url('./../assets/pixel.woff2') format('woff2'),
195 | url('./../assets/pixel.woff') format('woff'),
196 | url('./../assets/pixel.eot') format('embedded-opentype'),
197 | url('./../assets/pixel.ttf') format('truetype');
198 | /* Add other formats as you see fit */
199 | }
200 | ```
201 |
202 | ### How to load images
203 |
204 | #### In JavaScript
205 |
206 | You can require an image from JavaScript like
207 | ```js
208 | const myImage = require('./assets/icon.png');
209 | ```
210 |
211 | If the image size in bytes is smaller than `8192`you, `myImage` will be a string with the encoded image path such as
212 | ```
213 | data:image/svg+xml;base64,bW9kdWxlLmV4cG9ydHMgPSBfX3dlYnBhY2tfcHVibGljX3BhdGhfXyArICJhc3NldHMvaW1hZ2VzL3RpY2stQ3lydkhSdi5zdmciOw==
214 | ```
215 | If the image size is larger than `8192` it will be a string with the url to the image such as
216 | ```
217 | src/assets/icon.png?hash=5b1f36bc41ab31f5b801
218 | ```
219 |
220 | This limit is set so images like icons are not loaded through a request but you can force the loader to give you image urls always by doing the following but should not be necessary. The limit works 90% of the time.
221 | ```js
222 | const myImage = require('!!url!/assets/icon.png');
223 | ```
224 |
225 | #### In `index.html`
226 |
227 | If you would like to include an image on your `index.html` file, place the path of the image in a webpack require statement`<%= require(imagePath) %>`.
228 |
229 | ```html
230 |  %>){kind=logo}
233 | ```
234 |
235 | ### How to install Bootstrap 4
236 |
237 |
238 | **After the project has been kickstarted**
239 |
240 | Install bootstrap
241 | ````sh
242 | npm install bootstrap@4 --save
243 | ````
244 |
245 | Install bootstrap dependencies.
246 | ````sh
247 | npm install popper.js --save
248 | npm install jquery --save
249 | ````
250 |
251 | Replace the project `index.scss` with
252 |
253 | ````scss
254 | @import "~bootstrap/scss/bootstrap";
255 | ````
256 |
257 | And replace the project `index.js` with
258 | ````js
259 | require('./styles/index.scss');
260 |
261 | import PopperJs from 'popper.js';
262 | import jquery from 'jquery';
263 |
264 |
265 | jquery(()=>{
266 | console.log('Hello jQuery + bootstrap 4!');
267 | });
268 | ````
269 |
270 | To see it all come together, replace the index.html body tag with
271 |
272 | ````html
273 |
274 |
275 |
307 |
308 | Use this document as a way to quickly start any new project.
All you get is this text and a mostly barebones HTML document.
39 |
39 |