Start building your great modern static website with this boilerplate using Jekyll, React and Webapck.

Jekyll + React + Webpack Boilerplate

Start building your great modern static website with this boilerplate using Jekyll, React and Webapck.

Apr 7, 2019

  • Jekyll
  • React
  • Webpack

  • Introduction

    I am a huge fan of Jekyll and it’s a great tool to quickly create moderns static websites as I have shown in my previous posts - Building the Website - Part 1 and Part 2. However, if you want to include some more interactive pieces on your websites you can take advantage of node modules using npm packages manager and combine them using Webpack + Babel to “compile” your website. You can then use Gulp to add CSS, Image and JS minifications and React components to take advantage of the amazing React community.

    This is a boilerplate to start building your website using Jekyll, React and Webpack.

    It’s available on my GitHub: https://github.com/mlomboglia/jekyll-react-webpack

    References

    I have used as a base reference the great boilerplate built by Forestry team incorporating the ideas shared by Alli Zadrozny on his post “Using Webpack and React with Jekyll”. All the libraries have been updated, so you can now run Jekyll with React using Webpack as the wrapper.

    This boilerplate wraps Jekyll and React with Gulp as your local development build pipeline.

    PostCSS and Webpack + Babel are used for CSS and JS compiling & transpiling.

    BrowserSync is used for providing a modern local development experience, allowing you to preview your site on multiple devices in sync.

    BrowsersList is used for configuring Browser support.

    Installation

    Prerequisites

    To use Gulp, you must have Node and NPM installed.

    • Install npm: $ sudo install npm -g
    • Install webpack: $ npm install webpack -g
    • Install jekyll: $ gem install jekyll -g

    Setup

    Once the prerequisites are installed, clone the repository to your local machine, and then run:

    gem install bundle 
    bundle install 
    npm install
    

    This will install bundle and all of the needed to run your Jekyll environment. This may take a little while! :wink: You can use this as the base to create your CI/CD pipeline as well.

    Development

    All development tasks are performed using npm run. See "scripts" in package.json for a full list of commands.

    Local Development

    Local development is powered by BrowserSync, you will be able to develop sites rapidly through:

    • A local development server at http://localhost:3000/.
    • Automatic CSS updates without reloading the page
    • Automatic page reloads when content is changed

    Running the local development server is as simple as running:

    npm start
    

    This will display all draft, future-dated, or expired content, which is not included in your production build.

    If you’d like to develop with the site as it will appear in production, run:

    npm run preview
    

    Production Build

    To generate a final production build on your local machine you can run:

    npm run build
    

    Project Structure

    .
    ├── .tmp/                  // Temporary directory for development server
    ├── dist/                  // The production build
    ├── site/                  // The Jekyll project, with all content and static files
    |   ├── _data/             // YAML files containing site data 
    |   ├── _posts/            // Jekyll's built-in blogging content type
    |   ├── _layouts/          // Your theme layouts
    |   ├── _includes/         // Your theme partials
    |   ├── css/               // Where compiled CSS files live
    |   ├── js/                // Where compiled JS files live
    |   ├── img/               // Where theme images live
    |   ├── uploads/           // Where user uploads are stored
    |   ├── _config.yml        // Production configuration settings
    |   ├── _development.yml   // Settings for local development only
    |   ├── 404.md             // Error page for your site
    |   └── index.md           // Homepage of your site
    └─── config                // Config packs
    └─── scripts               // Forestry base scripts
    └─── src/
         ├── css               // CSS/SCSS source files to be compiled to /css/
         └── js                // JS source files to be compiled to /js/
          └── components       // Add your REACT components here /js/
          scripts.js           // REACT Base handler    
    

    Jekyll content will be served from the site folder. All the assets treated by webpack and gulp should be in the src.

    The production build files of your site will be copied to the dist folder.

    React Component

    The nice thing about having a webpack directory is now we can organize our components in a new folder and import the things needed in a modular way. Add your React components in the components/ folder. As an example, Hello.js is already available

    import React, { Component } from 'react';
      class Hello extends Component {
        render() {
          return (
            <div>Hello World</div>
        )
      }
    }
    export default Hello;
    

    In scripts.js load react and import your component:

    import React, { Component } from 'react';
    import {render} from 'react-dom';
    import Hello from './components/Hello';
    class App extends Component {
      render() {
        return (
          <Hello />
        )
      }
    }
    render(<App />, document.getElementById('root'));
    

    Add the div React that will render your component in your .html layout:

      <div id="root"></div>
      <script type="text/javascript" src="/assets/javascripts/bundle.js" charset="utf-8"></script>
    

    Run $ webpack to compile your js and $ jekyll build so Jekyll will catch the newly compiled file. You should now be able to see a lovely React component on your Jekyll page!

    Testing

    This boilerplate comes with standard ESLint and StyleLint configurations that will lint your CSS and JS for errors or common style issues, which work with most popular IDEs.

    The tests can also be run from the command line:

    • JS: npm run eslint
    • CSS: npm run stylelint

    If you want to automatically fix lint errors, you can do this from the command line as well:

    • JS: npm run eslint:fix
    • CSS: npm run stylelint:fix

    Cleanup

    This boilerplate is self-cleaning, and will remove the production dist/ and development .tmp/ folders every time a command is run to ensure that their contents are always up to date.

    If you wish to manually cleanup, run:

    npm run clean

    Configuration

    All config files are located in the config directory:

    • babel.config.js –> Babel presets and plugins
    • gulp.config.js –> Gulp tasks for “styles”, “scripts”, “images” and “svg”
    • webpack.config.js –> Webapck generation

    Paths

    All build source and destination paths can be configured from static-scripts.config.js.

    Jekyll

    The build commands for Jekyll can be configured from stat-cscripts.config.js.

    Four options are available:

    • default: the default build commands that are always run
    • development: additional build commands for the development server
    • preview: additional build commands for a production development server
    • production: additional build commands for production builds

    BrowserSync Development Server

    The configuration for BrowserSync is found in .browsersyncrc.js

    CSS/SASS

    The configuration for PostCSS is found in .postcssrc.js

    Browser support

    Both PostCSS and Webpack use .browserslistrc to decide on browser support when compiling.

    Licensing

    This boilerplate project is released under the MIT license.

    It’s available on my GitHub: https://github.com/mlomboglia/jekyll-react-webpack

    Congratulations!! :trophy: