dd-webpack-service

Simple Webpack service for generating Webpack 1.x configuration

Getting Started

Ensure you have a package.json (npm init) and that the required peer dependencies are installed:

npm i react react-dom react-hot-loader@3.0.0-beta.2 babel-polyfill --save
npm i webpack --save-dev

Install the webpack service:

npm i dd-webpack-service --save-dev

Create a webpack server file, e.g. server.js:

var path = require('path')
var webpackService = require('dd-webpack-service').webpackService

var isDevelopment = process.env.NODE_ENV !== 'production'

var config = webpackService.getConfig({
  isDevelopment: isDevelopment,
  entry: path.resolve(__dirname, './src/index.jsx'),
  output: {
    path: path.resolve(__dirname, './public'),
    filename: '[name].js',
  },
  html: {
    title: 'My App',
    appMountId: 'root',
  },
})

webpackService.run(config)

Create your application code in the folder referenced by your path property set above:

// index.jsx
import 'babel-polyfill'
import React from 'react'
import { render } from 'react-dom'
import { AppContainer } from 'react-hot-loader'
import App from './App'

render(
  <AppContainer>
    <App />
  </AppContainer>,
  document.getElementById('root')
)

if (module.hot) {
  module.hot.accept('./App', () => {
    // If you use Webpack 2 in ES modules mode, you can
    // use <App /> here rather than require() a <NextApp />.
    const NextApp = require('./App').default // eslint-disable-line global-require

    render(
      <AppContainer>
        <NextApp />
      </AppContainer>,
      document.getElementById('root')
    )
  })
}

// App.jsx
/* eslint-disable react/prefer-stateless-function */
import React, { Component } from 'react'

class App extends Component {
  render() {
    return (
      <div>
        <p>Test</p>
      </div>
    )
  }
}

export default App

Create an npm start script to run your server.js in package.json:

"scripts": {
  "start": "node server.js",
  ...
}

Navigate to http://localhost:8080 to view your application with hot module replacement.

Note if you wish to change the default port from 8080, then specify a port property within the options passed to webpackService.getConfig.

ES6/2015

You can also develop your server.js file in ES6/2015 by using babel-node within your package.json start script. Install the babel-cli package to have access to babel-node.

npm i babel-cli --save-dev

"scripts": {
  "start": "babel-node --presets es2015,stage-0,react server.js",
  ...
}

// server.js
import path from 'path'
import { webpackService } from 'dd-webpack-service'

const isDevelopment = process.env.NODE_ENV !== 'production'

const config = webpackService.getConfig({
  isDevelopment,
  entry: path.resolve(__dirname, './src/index.jsx'),
  output: {
    path: path.resolve(__dirname, './public'),
    filename: '[name].js',
  },
  html: {
    title: 'My App',
    appMountId: 'root',
  },
})

webpackService.run(config)

Webpack Production Build

To create a production build, you want to run the following build script in your package.json:

"build": "cross-env NODE_ENV=production webpack",

Note that cross-env is an npm package that allows you to set node environment variables cross platform, use npm i cross-env --save-dev to have access.

Webpack will need a webpack.config.js file in the project root which exports your Webpack configuration object.

Note that an alternative to using a webpack.config.js file for production builds is to use the Webpack JavaScript API to run Webpack. See the React Starter Kit source code for an example of this.

If you wish to use ES6 within your webpack config file, then you need to do the following two steps:

• Call your file webpack.config.babel.js
• Install the babel-register npm package (npm i babel-register --save-dev)
• Set babel presets "es2015" (and "stage-0" if you want latest features) either in a .babelrc file or within a babel section in your package.json file

With these in place, you can then seperate out your Webpack options into a separate webpack.config.babel.js file:

// webpack.config.babel.js
import webpack from 'webpack'
import { webpackService } from 'dd-webpack-service'
import options from './options'
import packages from './package.json'

const isDevelopment = process.env.NODE_ENV !== 'production'

const config = webpackService.getConfig({
  isDevelopment: isDevelopment,
  port: 3000,
  ... other webpack settings here
})

// In production, use separate vendor chunk
// See https://github.com/webpack/webpack/issues/1189
if (!isDevelopment) {
  config.entry = {
    'js/main': options.entry,
    'vendor': Object.keys(packages.dependencies)
  }

  config.plugins.splice(
    1,
    0,
    new webpack.optimize.CommonsChunkPlugin('vendor', 'js/vendor.js')
  )
}

export default config

The server.js file can then be simplified to:

import { webpackService } from 'dd-webpack-service'
import config from './webpack.config.babel'

webpackService.run(config)

Testing

In order to run tests with Webpack, dd-webpack-service uses Karma Webpack. Firstly, you can set your test scripts within package.json:

"scripts": {
  ...
  "test": "karma start",
  "test:watch": "npm test -- --auto-watch --no-single-run --reporters progress"
},

Next, Karma requires a karma.config.js file which exports a function which takes the Karma config to set any Karma related options. Part of these options is a webpack section which takes the Webpack configuration.

dd-webpack-service provides a KarmaService which can take a webpack configuration object, and the Karma config object, and return a Karma configuration object with sensible defaults. The dd-webpack-service WebpackService provides a getTestConfig function which provides a sensible Webpack test configuration.

// karma.config.js
var webpackService = require('dd-webpack-service').webpackService
var karmaService = require('dd-webpack-service').karmaService
var options = require('./options.js')

module.exports = function setKarmaConfig(config) {
  const webpackConfig = webpackService.getTestConfig(options)
  const karmaConfig = karmaService.getConfig(config, webpackConfig)
  config.set(karmaConfig)
}

// options.js
var path = require('path')

module.exports = {
  entry: path.resolve(__dirname, './demo/index.jsx'),
  output: {
    path: path.resolve(__dirname, './demo'),
    filename: '[name].js',
  },
  html: {
    title: 'My App',
    appMountId: 'root',
  },
}

Using a separate ES5 based options.js file allows us to share the Webpack configuration options between Karma and our webpack configuration file.

ES6 / 2015

Currently Karma configuration files do not yet support ES6/2015.

However, a workaround is to use babel-register within your karma.conf.js file before requiring an ES6/2015 based configuration file:

// karma.conf.js
require('babel-core/register');
module.exports = require('./karma.conf.babel').default;

// karma.conf.babel.js
import { webpackService, karmaService } from 'dd-webpack-service'
import options from './options'

export default config => {
  const webpackConfig = webpackService.getTestConfig(options)
  const karmaConfig = karmaService.getConfig(config, webpackConfig)
  config.set(karmaConfig)
}

Note that tests should be written in __tests__ folders and follow the *-spec.js naming convention

Developers

For maintainers of dd-webpack-service:

Initial Setup

npm set init.author.name "..."
npm set init.author.email "...@..."
npm set init.author.url "http://..."
npm adduser

Publishing

• Increment version in package.json

npm run push

Note the push script will run the build npm run build and then npm publish to push the package to the npm registry (https://registry.npmjs.org).