# universal-webpack [![NPM Version][npm-badge]][npm] [![Test Coverage][coveralls-badge]][coveralls] **For beginners:** consider trying [Next.js](https://github.com/zeit/next.js) first: it's user-friendly and is supposed to be a good start for people not wanting to deal with configuring Webpack manually. On the other hand, if you're an experienced Webpack user then setting up `universal-webpack` shouldn't be too difficult. This library generates client-side and server-side configuration for Webpack therefore enabling seamless client-side/server-side Webpack builds. Requires some initial set up and some prior knowledge of Webpack. ## Install ``` npm install universal-webpack --save-dev ``` ## Example project You may refer to [this sample project](https://github.com/catamphetamine/webpack-react-redux-server-side-render-example) as a reference example of using this library (see `webpack` directory, `package.json` and `rendering-service/main.js`). ## Use Suppose you have a typical `webpack.config.js` file. Create two new files called `webpack.config.client.babel.js` and `webpack.config.server.babel.js` with the following contents: ### webpack.config.client.babel.js ```js import { client } from 'universal-webpack/config' import settings from './universal-webpack-settings' import configuration from './webpack.config' // Create client-side Webpack config. export default client(configuration, settings) ``` ### webpack.config.server.babel.js ```js import { server } from 'universal-webpack/config' import settings from './universal-webpack-settings' import configuration from './webpack.config' // Create server-side Webpack config. export default server(configuration, settings) ``` Where `./universal-webpack-settings.json` is a configuration file for `universal-webpack` (see below, leave empty for now). Now, use `webpack.config.client.babel.js` instead of the old `webpack.config.js` for client side Webpack builds. Your setup also most likely differentiates between a "development" client side Webpack build and a "production" one, in which case `webpack.config.client.babel.js` is further split into two files — `webpack.config.client.dev.babel.js` and `webpack.config.client.prod.babel.js` — each of which inherits from `webpack.config.client.babel.js` and makes the necessary changes to it as defined by your particular setup. And, `webpack.config.server.babel.js` file will be used for server-side Webpack builds. And, analogous to the client-side config, it also most likely is gonna be split into "development" and "production" configs, as defined by your particular setup. Setting up the server side requires an additional step: creating the "entry" file for running the server. The reason is that client-side config is created from `webpack.config.js` which already has Webpack ["entry"](https://webpack.js.org/concepts/entry-points/) defined. Usually it's something like `./src/index.js` which is the "main" file for the client-side application. Server-side needs such a "main" file too and the path to it must be configured in `./universal-webpack-settings.json` as `server.input`: ### universal-webpack-settings.json ```js { "server": { "input": "./source/server.js", "output": "./build/server/server.js" } } ``` With the server-side "entry" file path configured, the server-side config created by this library will have the Webpack "entry" parameter set up properly. A "server-side" Webpack build will now produce a "server-side" bundle (`./build/server/server.js`) which can be run using Node.js. An example of an "entry" file: ### source/server.js ```js import path from 'path' import http from 'http' import express from 'express' import httpProxy from 'http-proxy' // React routes. // (shared with the client side) import routes from '../client/routes.js' // Redux reducers. // (shared with the client side) import reducers from '../client/reducers.js' // Starts the server. function startServer() { // Create HTTP server. const app = new express() const server = new http.Server(app) // Serve static files. app.use(express.static(path.join(__dirname, '..', 'build/assets'))) // Proxy API calls to API server. const proxy = httpProxy.createProxyServer({ target: 'http://localhost:xxxx' }) app.use('/api', (req, res) => proxy.web(req, res)) // React application rendering. app.use((req, res) => { // Match current URL to the corresponding React page. routerMatchURL(routes, req.originalUrl).then((error, routingResult) => { if (error) { throw error } // Render React page. const page = createPageElement(routingResult, reducers) res.status(200) res.send('...' + ReactDOM.renderToString(page) + '...') }) .catch((error) => { res.status(500) return res.send('Server error') }) }) // Start the HTTP server. server.listen() } // Run the server. startServer() ``` The main use-case for `universal-webpack` though is most likely "Server-Side Rendering" which means that the server is somehow gonna need to know the actual URLs for the compiled javascript and CSS files (which contain random-generated md5 hashes). Specifically for this case this library provides a special "runner" for the server-side bundle which requires that the server-side bundle just exports a "start server" function, without actually running the server, and then such "start server" function will be called with a special `parameters` argument which holds the actual URLs for the compiled javascript and CSS files (see the "Chunks" section below). So in this case the changes to the server file are gonna be: ### source/server.js ```js ... export default function startServer(parameters) { ... } // Don't start the server manually. // // Run the server. // startServer() ``` And the server-side runner will be called like this: ### source/start-server.js ```js // The runner. var startServer = require('universal-webpack/server') // The server-side bundle path info. var settings = require('../universal-webpack-settings') // Only `configuration.context` and `configuration.output.path` // parameters are used from the whole Webpack config. var configuration = require('../webpack.config') // Run the server. startServer(configuration, settings) ``` Running `node source/start-server.js` will basically call the function exported from `source/server.js` with the `parameters` argument. Finally, to run all the things required for "development" mode (in parallel): ```bash # Client-side build. webpack-dev-server --hot --config ./webpack.config.client.dev.babel.js ``` ```bash # Server-side build. webpack --watch --config ./webpack.config.server.dev.babel.js --colors --display-error-details ``` ```bash # Run the server. nodemon ./source/start-server --watch ./build/server ``` For production mode the command sequence would be: ```bash # Build the client. webpack --config "./webpack.config.client.babel.js" --colors --display-error-details # Build the server. webpack --config "./webpack.config.server.babel.js" --colors --display-error-details # Run the server. node "./source/start-server" ``` ## Chunks This library will pass the `chunks()` function parameter (inside the `parameters` argument of the server-side function) which returns webpack-compiled chunks filename info: ### build/webpack-chunks.json ```js { javascript: { main: `/assets/main.785f110e7775ec8322cf.js` }, styles: { main: `/assets/main.785f110e7775ec8322cf.css` } } ``` These filenames are required for ` ``` ## resolve.moduleDirectories If you were using `resolve.moduleDirectories` for global paths instead of relative paths in your code then consider using `resolve.alias` instead ```js resolve: { alias: { components: path.resolve(__dirname, '../src/components'), ... } } ``` ## `universal-webpack` vs `webpack-isomorphic-tools` Note: If you never heard of `webpack-isomorphic-tools` then you shouldn't read this section. `webpack-isomorphic-tools` runs on the server-side and hooks into Node.js `require()` function with the help of `require-hacker` and does what needs to be done. `universal-webpack` doesn't hook into `require()` function - it's just a helper for transforming client-side Webpack configuration to a server-side Webpack configuration. It doesn't run on the server-side or something. It's just a Webpack configuration generator - turned out that Webpack has a `target: "node"` parameter which makes it output code that runs on Node.js without any issues. I wrote `webpack-isomorphic-tools` before `universal-webpack`, so `universal-webpack` is the recommended tool. However many people still use `webpack-isomorphic-tools` (including me) and find it somewhat less complicated for beginners. ## GitHub On March 9th, 2020, GitHub, Inc. silently [banned](https://medium.com/@catamphetamine/how-github-blocked-me-and-all-my-libraries-c32c61f061d3) my account (and all my libraries) without any notice. I opened a support ticked but they didn't answer. Because of that, I had to move all my libraries to [GitLab](https://gitlab.com/catamphetamine). ## License [MIT](LICENSE) [npm]: https://www.npmjs.org/package/universal-webpack [npm-badge]: https://img.shields.io/npm/v/universal-webpack.svg?style=flat-square [travis]: https://travis-ci.org/catamphetamine/universal-webpack [travis-badge]: https://img.shields.io/travis/catamphetamine/universal-webpack/master.svg?style=flat-square [coveralls]: https://coveralls.io/r/catamphetamine/universal-webpack?branch=master [coveralls-badge]: https://img.shields.io/coveralls/catamphetamine/universal-webpack/master.svg?style=flat-square

	Stars	Issues	Version	Updated	Created
iso-morphic-style-loader	16	1	2.0.1	7 years ago	7 years ago
isomorphic-style-loader	1,273	90	5.3.2	3 years ago	9 years ago
universal-webpack			0.8.5	2 years ago	8 years ago

iso-morphic-style-loader vs isomorphic-style-loader vs universal-webpack

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Sick of boring JavaScript newsletters?

Downloads in past