11 |
12 | Elf is a simple, magical [Eleventy](https://www.11ty.dev/) starter kit to help you create a project using standard technologies like webpack, Babel and Sass, while also considering ease of use, performance and browser compatibility.
13 |
14 | If you'd like to know why Elf exists and how best to take advantage of it, read [Creating a production-ready Eleventy project with webpack, Babel and Sass](https://dev.to/stowball/creating-a-production-ready-eleventy-project-with-webpack-babel-and-sass-35ep).
15 |
16 | ## Getting started
17 |
18 | 1. Clone or fork this repo: `git clone https://github.com/stowball/elf`
19 | 2. `cd` into the project directory and run `npm install`
20 |
21 | ## Running and serving a dev build
22 |
23 | ```sh
24 | npm run dev
25 | ```
26 |
27 | Browse to [http://localhost:8080](http://localhost:8080).
28 |
29 | ## Running and serving a prod build
30 |
31 | ```sh
32 | npm run prod
33 | npm run serve:prod
34 | ```
35 |
36 | Browse to [http://localhost:5000](http://localhost:5000).
37 |
38 | ## Technologies used
39 |
40 | * [Eleventy](https://www.11ty.dev/)… obviously
41 | * [EJS](https://ejs.co/) as the templating language
42 | * [Sass](https://sass-lang.com/) for writing CSS
43 | * [Babel](https://babeljs.io/) for transpiling and polyfilling JavaScript
44 | * [Autoprefixer](https://github.com/postcss/autoprefixer) for vendor prefixing CSS
45 | * [Webpack](https://webpack.js.org/) for compiling the Sass and JavaScript assets
46 | * [ESLint](https://eslint.org/) and [Airbnb's base configuration](https://www.npmjs.com/package/eslint-config-airbnb-base) for linting
47 |
48 | ## Project structure
49 |
50 | ```
51 | src/
52 | _components/
53 | All UI partials
54 | _data/
55 | Eleventy data files
56 | _layouts/
57 | Base page layouts
58 | _pages/
59 | Each individual page template
60 | assets/
61 | css/
62 | index.scss
63 | All other scss files
64 | js/
65 | index.js
66 | All other js files
67 | images/
68 | All images used
69 | Configuration and build files
70 | ```
71 |
72 | Files in `assets` will be handled by webpack, Eleventy will transform all of the directories with a leading `_`, and will copy across any `images`.
73 |
74 | Eleventy’s output will be to a `dist` directory at the root level.
75 |
--------------------------------------------------------------------------------
/tutorial.md:
--------------------------------------------------------------------------------
1 | # Creating a production-ready Eleventy project with webpack, Babel and Sass
2 |
3 | While [Eleventy](https://www.11ty.dev/) is a magnificent, and increasingly popular static site generator (SSG), I’ve found it hard to find good references on starting a project using standard technologies like [webpack](https://webpack.js.org/), [Babel](https://babeljs.io/) and [Sass](https://sass-lang.com/), so decided to write this tutorial.
4 |
5 | Before we start, it’s important to know that I’m not going to describe any technology in great detail, so I’ll assume you have a basic understanding of the “front-end” stack, and have [Node.js](https://nodejs.org/en/) installed (both v10.15 and v14.5 have been tested and work perfectly).
6 |
7 | It’s also not a comprehensive guide to Eleventy. There are other resources for that, with [Learn Eleventy From Scratch](https://piccalil.li/course/learn-eleventy-from-scratch/) seemingly a great option. While I have only read the free, first lesson, I see many positive comments from the wider community so feel free to check it out.
8 |
9 | Let’s take a look at what we’ll cover:
10 |
11 | * [Setup](#setup)
12 | * [Configuring Eleventy](#configuring-eleventy)
13 | * [Creating a layout](#creating-a-layout)
14 | * [Creating our first page](#creating-our-first-page)
15 | * [Serving our site](#serving-our-site)
16 | * [Re-writing URLs](#re-writing-urls)
17 | * [Setting up webpack](#setting-up-webpack)
18 | * [Creating our assets](#creating-our-assets)
19 | * [Installing our dependencies](#installing-our-dependencies)
20 | * [Creating our configs](#creating-our-configs)
21 | * [Adding the assets to our Eleventy site](#adding-the-assets-to-our-eleventy-site)
22 | * [Updating our Eleventy config](#updating-our-eleventy-config)
23 | * [Improving our cache busting](#improving-our-cache-busting)
24 | * [Serving our prod build](#serving-our-prod-build)
25 | * [Cleaning our prod build](#cleaning-our-prod-build)
26 | * [Minifying our HTML for prod](#minifying-our-html-for-prod)
27 | * [Implementing Babel for polyfilling and transpilation](#implementing-babel-for-polyfilling-and-transpilation)
28 | * [Vendor prefixing CSS with Autoprefixer](#vendor-prefixing-css-with-autoprefixer)
29 | * [A Git gotcha - my assets aren’t updating!](#a-git-gotcha---my-assets-arent-updating)
30 | * [Wrapping up](#wrapping-up)
31 |
32 | ## Setup
33 |
34 | Open a terminal in a new project directory, and run:
35 |
36 | ```sh
37 | npm init -y
38 | ```
39 |
40 | Next up, install Eleventy:
41 |
42 | ```sh
43 | npm install @11ty/eleventy --save-dev --save-exact
44 | ```
45 |
46 | ## Configuring Eleventy
47 |
48 | I prefer to keep all source files in a root `src` directory, with the full folder structure looking like this:
49 |
50 | ```
51 | src/
52 | _components/
53 | All UI partials
54 | _data/
55 | Eleventy data files
56 | _layouts/
57 | Base page layouts
58 | _pages/
59 | Each individual page template
60 | assets/
61 | css/
62 | index.scss
63 | All other scss files
64 | js/
65 | index.js
66 | All other js files
67 | images/
68 | All images used
69 | Configuration and build files
70 | ```
71 |
72 | Files in `assets` will be handled by webpack, Eleventy will transform all of the directories with a leading `_`, and will copy across any `images`.
73 |
74 | When the site is built, we’ll configure Eleventy to output it to a `dist` directory at the root level.
75 |
76 | I prefer to use [EJS](https://ejs.co/) as my templating language because it’s the closest to being “just JavaScript” while also providing a simple developer experience for writing standard HTML.
77 |
78 | OK, so let’s configure Eleventy to support the above structure.
79 |
80 | First, create an `.eleventy.js` file in the project root with the following:
81 |
82 | ```js
83 | module.exports = function(eleventyConfig) {
84 | return {
85 | dir: {
86 | includes: '_components',
87 | input: 'src',
88 | layouts: '_layouts',
89 | output: 'dist',
90 | },
91 | // Allows using markup and EJS features in markdown
92 | markdownTemplateEngine: 'ejs',
93 | templateFormats: [
94 | 'ejs',
95 | 'md',
96 | ],
97 | };
98 | };
99 | ```
100 |
101 | The above assumes that you’ll be using `.ejs` or `.md` files for your templating, so I recommend you install an appropriate syntax highlighter for your editor.
102 |
103 | ## Creating a layout
104 |
105 | [Layouts](https://www.11ty.dev/docs/layouts/) are special templates that can be used to wrap other content, which in our case will be the base, page-level HTML markup.
106 |
107 | In `src/_layouts`, let’s create a `default.ejs` file with the following:
108 |
109 | ```html
110 |
111 |
112 |
113 |
114 |
115 |
116 | <%= locals.title %>
117 |
118 |
119 | <%- content -%>
120 |
121 |
122 | ```
123 |
124 | For the most part, this is a standard HTML file, but we have 2 uses of EJS syntax:
125 |
126 | ```
127 | <%= locals.title %>
128 | ```
129 |
130 | Will output an escaped page `title` here. In EJS, it’s safer to always prefix your variables with `locals.`, that way you can easily support `undefined` variables in your templates.
131 |
132 | ```
133 | <%- content -%>
134 | ```
135 |
136 | Eleventy provides a `content` variable, so this will render any page content (unescaped) that uses this layout within this block.
137 |
138 | ## Creating our first page
139 |
140 | In `src/_pages`, let’s create an `index.md` with the following:
141 |
142 | ```md
143 | ---
144 | title: My cool website
145 | layout: default.ejs
146 | ---
147 |
148 | # Hello, world
149 |
150 | Welcome to my website.
151 |
152 | A random number is <%- Math.random() %>
153 | ```
154 |
155 | The part between `---` is called [front matter](https://www.11ty.dev/docs/data-frontmatter/), where we can define whatever variables we like, as well as make use of some built-in ones provided by Eleventy.
156 |
157 | We’ve defined what our page `title` will be (which is consumed within our `default` layout), and the `layout` to use.
158 |
159 | We’re using markdown which will be converted to an `
` and `
`s, and demonstrating that you can also use EJS features (and JavaScript) within markdown itself.
160 |
161 | ## Serving our site
162 |
163 | With our page created, how do we serve it up locally and see changes as we update the content and create new pages?
164 |
165 | Let’s head over to `package.json`, and update our `"scripts"` with this:
166 |
167 | ```
168 | "scripts": {
169 | "build:site": "ELEVENTY_ENV=production npx eleventy",
170 | "dev:site": "ELEVENTY_ENV=development npx eleventy --serve"
171 | },
172 | ```
173 |
174 | Now, from a terminal, you can run `npm run dev:site` and browse to [http://localhost:8080/_pages/](http://localhost:8080/_pages/) to see your HTML page fully rendered.
175 |
176 | We’ve also added a command to perform a production build, but we won’t need to use that just yet. Also note the `ELEVENTY_ENV=production|development`. This provides us the ability to do different things with our Eleventy process, like minifying HTML, depending on the build type.
177 |
178 | ## Re-writing URLs
179 |
180 | But wait up, we don’t want users (or us) to have to browse to `/_pages` in every URL; that home page should be available at the root domain!
181 |
182 | Thankfully, Eleventy has a feature called [permalinks](https://www.11ty.dev/docs/permalinks/), which allows you to set what the URL for each page will be. Now, while we can manually add this to every page’s front matter to remove `_pages`, we can go one better by automating that.
183 |
184 | Let’s create a `_pages.json` in `src/_pages`, with the following:
185 |
186 | ```json
187 | {
188 | "permalink": "<%- page.filePathStem.replace('/_pages', '').replace('/index', '') %>/index.html"
189 | }
190 | ```
191 |
192 | “What is this madness?”, I hear you cry. Well, since we can use JavaScript within EJS, and use EJS within JSON, we can use the `page.filePathStem` which Eleventy provides to construct a new, better permalink path.
193 |
194 | As an example, for the following files:
195 |
196 | ```
197 | /_pages/index.md
198 | /_pages/foo/index.ejs
199 | /_pages/foo/bar.md
200 | /_pages/foo/baz/index.ejs
201 | /_pages/foo/baz/qux.md
202 | ```
203 |
204 | Eleventy will provide the following `filePathStem`s:
205 |
206 | ```
207 | /_pages/index
208 | /_pages/foo/index
209 | /_pages/foo/bar
210 | /_pages/foo/baz/index
211 | /_pages/foo/baz/qux
212 | ```
213 |
214 | So, this “script” first removes the `/_pages` from the `filePathStem` string, then removes any trailing `/index` so every page is “equal”, and finally appends `/index.html`, which, for the above path examples, results in:
215 |
216 | ```
217 | /index.html
218 | /foo/index.html
219 | /foo/bar/index.html
220 | /foo/baz/index.html
221 | /foo/baz/qux/index.html
222 | ```
223 |
224 | Now, you should be able to browse directly to [http://localhost:8080/](http://localhost:8080/) to see your “Hello, world” file, and the correct path for any other file you create later on.
225 |
226 | While this is kinda cool, it’s completely unstyled, so let’s see how we can set up webpack to compile CSS using Sass.
227 |
228 | ## Setting up webpack
229 |
230 | ### Creating our assets
231 |
232 | Before we do any webpack configuration, let’s first scaffold our assets so we have something to configure.
233 |
234 | We’re going to use Sass, which, while it may be going out of favour in some circles, still does an excellent job at allowing us to write more maintainable CSS.
235 |
236 | *As a side note, I still like Sass so much that I’ve used it to create an atomic CSS library called [Hucssley](https://github.com/stowball/hucssley), which, in my humble opinion, is excellent!*
237 |
238 | Anyway, back to this project…
239 |
240 | Create `src/assets/css/index.scss` with the following code:
241 |
242 | ```css
243 | html {
244 | font-family: sans-serif;
245 | background: #cbe3f5;
246 | }
247 | ```
248 |
249 | In this directory, you would add all of your project’s Sass partials and `@import` them from `index.scss`.
250 |
251 | *If you prefer to co-locate your CSS and components, you could just as easily store them in specific template folders within `_components` and `@import` from there as well.*
252 |
253 | For webpack to handle our CSS, it must be `import`ed into a JavaScript file, so let’s create `src/assets/js/index.js` with the following:
254 |
255 | ```js
256 | import '../css/index.scss';
257 |
258 | console.log('Hello again');
259 | ```
260 |
261 | Although we `import` the CSS within in JavaScript, this is not CSS-in-JS; it’s purely so webpack can do its thing™.
262 |
263 | ### Installing our dependencies
264 |
265 | Now that we have our asset files, let’s begin with the setup.
266 |
267 | First, we’re going to need to install quite a few dependencies now, so kill your `dev:site` process, and run this in the terminal.
268 |
269 | ```sh
270 | npm install css-loader fibers mini-css-extract-plugin optimize-css-assets-webpack-plugin sass sass-loader terser-webpack-plugin webpack webpack-cli webpack-merge --save-dev --save-exact
271 | ```
272 |
273 | ### Creating our configs
274 |
275 | In the previous step, we installed a dependency called [webpack-merge](https://www.npmjs.com/package/webpack-merge). This will allow us to have separate development and production configurations which share the same, common configuration.
276 |
277 | In the project root, create `webpack.config.common.js` with the following:
278 |
279 | ```js
280 | // Makes Sass faster!
281 | const Fiber = require('fibers');
282 | const MiniCssExtractPlugin = require('mini-css-extract-plugin');
283 | const path = require('path');
284 |
285 | module.exports = {
286 | // Our "entry" point
287 | entry: './src/assets/js/index.js',
288 | output: {
289 | // The global variable name any `exports` from `index.js` will be available at
290 | library: 'SITE',
291 | // Where webpack will compile the assets
292 | path: path.resolve(__dirname, 'src/compiled-assets'),
293 | },
294 | module: {
295 | rules: [
296 | {
297 | // Setting up compiling our Sass
298 | test: /\.scss$/,
299 | use: [
300 | {
301 | loader: MiniCssExtractPlugin.loader,
302 | },
303 | {
304 | loader: 'css-loader',
305 | options: {
306 | url: false,
307 | },
308 | },
309 | {
310 | loader: 'sass-loader',
311 | options: {
312 | implementation: require('sass'),
313 | sassOptions: {
314 | fiber: Fiber,
315 | outputStyle: 'expanded',
316 | },
317 | },
318 | },
319 | ],
320 | },
321 | ],
322 | },
323 | // Any `import`s from `node_modules` will compiled in to a `vendor.js` file.
324 | optimization: {
325 | splitChunks: {
326 | cacheGroups: {
327 | commons: {
328 | test: /[\\/]node_modules[\\/]/,
329 | name: 'vendor',
330 | chunks: 'all',
331 | },
332 | },
333 | },
334 | },
335 | plugins: [
336 | new MiniCssExtractPlugin({
337 | filename: '[name].css',
338 | }),
339 | ],
340 | };
341 | ```
342 |
343 | Now, let’s create our development config, at `webpack.config.dev.js`:
344 |
345 | ```js
346 | const { merge } = require('webpack-merge');
347 | const common = require('./webpack.config.common.js');
348 |
349 | module.exports = merge(common, {
350 | mode: 'development',
351 | // Allow watching and live reloading of assets
352 | watch: true,
353 | });
354 | ```
355 |
356 | And finally, our production config, at `webpack.config.prod.js`:
357 |
358 | ```js
359 | const OptimizeCssAssetsPlugin = require('optimize-css-assets-webpack-plugin');
360 | const TerserPlugin = require('terser-webpack-plugin');
361 | const { merge } = require('webpack-merge');
362 | const common = require('./webpack.config.common.js');
363 |
364 | module.exports = merge(common, {
365 | // Enable minification and tree-shaking
366 | mode: 'production',
367 | optimization: {
368 | minimizer: [
369 | new OptimizeCssAssetsPlugin({}),
370 | new TerserPlugin({
371 | extractComments: false,
372 | }),
373 | ],
374 | },
375 | });
376 | ```
377 |
378 | Now we have our configs, we need scripts to run them. Head over to `package.json`, and add 2 new scripts:
379 |
380 | ```
381 | "build:assets": "webpack --config webpack.config.prod.js",
382 | "dev:assets": "webpack --config webpack.config.dev.js",
383 | ```
384 |
385 | so it should look like this:
386 |
387 | ```json
388 | "scripts": {
389 | "build:assets": "webpack --config webpack.config.prod.js",
390 | "build:site": "ELEVENTY_ENV=production npx eleventy",
391 | "dev:assets": "webpack --config webpack.config.dev.js",
392 | "dev:site": "ELEVENTY_ENV=development npx eleventy --serve"
393 | },
394 | ```
395 |
396 | *Note: JSON doesn’t allow trailing commas on the last line of an object, so all of the updates I suggest are correct if adding them alphabetically.*
397 |
398 | If you run `npm run build:assets` in your terminal, you should now have 2, minified files generated at:
399 |
400 | ```
401 | src/compiled-assets/main.css
402 | src/compiled-assets/main.js
403 | ```
404 |
405 | ### Adding the assets to our Eleventy site
406 |
407 | Let’s open up our `src/_layouts/default.ejs`, and in the `
`, add a reference to the stylesheet, and before the closing ``, add a reference to our JavaScript files.
408 |
409 | ```html
410 |
411 | … existing tags
412 |
413 |
414 | ```
415 |
416 | ```html
417 |
418 |
419 |
420 | ```
421 |
422 | We’ve also added some simplistic cache busting using the current timestamp (but we’ll improve that for production later on).
423 |
424 | If you’re wondering why we have a commented out `vendor.js` `
7 |
8 | # Elf
9 |
10 |