isomorphic-loader
v4.5.0
Published
Webpack isomorphic loader tools to make Node require handle files like images for Server Side Rendering (SSR)
Downloads
863
Maintainers
Readme
Webpack Isomorphic Loader
Webpack loader and tools to make node.js require
understands files such as images when you are doing server side rendering (SSR).
Purpose
With webpack and file-loader, you can do things like this in your React code:
import smiley from "./images/smiley.jpg";
render() {
return <div><img src={smiley} /></div>
}
That works out nicely, but if you need to do SSR, you will get SyntaxError
from node.js require
. That's because require
only understands JS files.
With this module, you can extend require
so it understands these files.
It contains three parts:
- a webpack loader - to mark asset files
- a webpack plugin - collect asset files and generate mapping data
- a node.js library - extend
require
for SSR using the mapping data
Install
$ npm install isomorphic-loader --save
Usage
Configuring Webpack
First use the webpack loader isomorphic-loader
to mark all your asset files that you want extendRequire
to handle.
The webpack loader
isomorphic-loader
is just a simple pass thru loader to mark your files. It will not do anything to the file content.
Next install the webpack plugin IsomorphicLoaderPlugin
to collect and save the list of the marked files.
For example, in the webpack config, to mark the usual image files to be understood by extendRequire
:
const { IsomorphicLoaderPlugin } = require("isomorphic-loader");
module.exports = {
plugins: [new IsomorphicLoaderPlugin()],
module: {
loaders: [
{
test: /\.(jpe?g|png|gif|svg)$/i,
loader: "file!isomorphic"
}
]
}
};
You can also mark any file in your code directly:
import smiley from "file!isomorphic!./images/smiley.jpg";
Extending node.js require
With the marked asset files collected, initialize extendRequire
with the mapping data before your server starts:
const { extendRequire } = require("isomorphic-loader");
const isomorphicRequire = extendRequire();
// isomorphicRequire is an instance of the ExtendRequire class exported from the module
// start your server etc
It will try to load the isomorphic config data from dist/isomorphic-assets.json
. You can also pass in the config data:
extendRequire(options, require("./dist/isomorphic-assets.json"));
Custom Config Overrides
When calling extendRequire
, you can pass in a callback in options.processConfig
to override the isomorphicConfig
extendRequire({
processConfig: config => {
// do something with config
return config;
}
});
Activating and Deactivating extendRequire
deactivate
API - deactivateextendRequire
during run time.activate
API - activateextendRequire
during run time.
const { extendRequire } = require("isomorphic-loader");
const isomorphicRequire = extendRequire();
isomorphicRequire.deactivate();
// and reactivate it
isomorphicRequire.activate();
Usage with CDN Server
If you publish your assets to a Content Delivery Network server, and if it generates a new unique path for your assets, then you likely have to set publicPath
after webpack compiled your project.
That's why webpack's document has this note in the section about publicPath
:
Note: In cases when the eventual
publicPath
of output files isn't known at compile time, it can be left blank and set dynamically at runtime in the entry point file. If you don't know thepublicPath
while compiling you can omit it and set__webpack_public_path__
on your entry point.
In that case, you would have to save the path CDN created for you and pass it to extendRequire
with a custom config override, or you can just modify the config file directly.
If your CDN server generates an unique URL for every asset file instead of a single base path, then you have to do some custom post processing to update the asset mapping files yourself.
Webpack Dev Server
If you are using webpack dev server, then you probably have two separate processes running:
- webpack dev server (WDS)
- your app's node.js server (APP)
And IsomorphicLoaderPlugin
would be running in WDS but extendRequire
is in APP.
- You need to setup some way to transfer the mapping data from WDS to APP.
- When starting up, APP needs to wait for the first mapping data before actually startup, unless your SSR code is not loaded until it's actually invoked.
Here is an example using chokidar to transfer the data through a file:
- In your
webpack.config.js
:
const fs = require("fs");
const { IsomorphicLoaderPlugin } = require("isomorphic-loader");
const isoPlugin = new IsomorphicLoaderPlugin();
isoPlugin.on("update", data => {
fs.writeFileSync("./tmp/isomorphic-assets.json", JSON.stringify(data.config));
});
module.exports = {
plugins: [isoPlugin]
};
- In your app server
index.js
const { extendRequire } = require("isomorphic-loader");
// figure out if running in dev mode or not
if (process.env.NODE_ENV !== "production") {
const chokidar = require("chokidar");
const assetFile = "./tmp/isomorphic-assets.json";
let isomorphicRequire;
function updateIsomorphicAssets() {
const firstTime = !isomorphicRequire;
if (firstTime) {
isomorphicRequire = extendRequire();
} else {
// do the necessary require cache refresh so hot module reload works in SSR
}
isomorphicRequire.loadAssets(assetFile);
if (firstTime) {
startServer();
}
}
const watcher = chokidar.watch(assetFile, { persistent: true });
watcher.on("add", updateIsomorphicAssets);
watcher.on("change", updateIsomorphicAssets);
// do some timeout check
setTimeout(() => {
if (!isomorphicRequire) {
console.error("timeout waiting for webpack dev server");
}
}, 20000).unref();
} else {
extendRequire().loadAssets("./dist/isomorphic-assets.json");
startServer();
}