CesiumJS and Webpack
require statements. When building, it will trace code dependencies and pack these modules into one or more bundles that are loaded by the browser.
In the first half of this tutorial, we’ll build a simple web app from the ground up using webpack, and then cover the steps to integrate the Cesium npm module. This is a good place to start if you’d like to use CesiumJS to develop a web application. If you’re new to Cesium and are looking to learn to build your first sample app, take a look at our Getting Started Tutorial.
In the second half, we’ll explore more advanced webpack configurations for optimizing an application using CesiumJS.
The complete code and tips for optimizing a CesiumJS webpack app can be found in the official cesium-webpack-example repository.
- An IDE or code editor. Developers on the Cesium team members use Visual Studio Code, but a minimal code editor such as Sublime Text will also work.
- Node.js installed. We recommend using the latest LTS version.
Create a basic webpack app
In this section, we’ll describe how to set up a basic web app with webpack and a development server. If you’ve already got an app set up and just want to add CesiumJS, skip to Add CesiumJS to a webpack app.
Initialize an app with npm
Create a new
cesium-webpack-app directory for your app. Open a console, navigate to the new directory, and run the following command:
Follow the prompts and populate any details about your app. Press enter to use the defaults. This will create
Create the app code
src directory for our app code. When we build the app, webpack will produce distribution files in a
src/index.html and add code for a boilerplate HTML page.
src/index.js and add this text code.
Install and configure webpack
Begin by installing webpack.
webpack.config.js to define our webpack configuration object.
context specifies the base path for the files.
entry is used to specify bundles. In this case, the
app bundle has
src/index.js as the entry point. webpack will output the bundle
app.js to the
webpack.config.js: one for CSS files and one for other static files. For each, define
test for the types of file to load, and
use to specify the list of loaders.
Require the plugin in
webpack.config.js and add it to
src/index.html as our
Bundle the app
package.json to define scripts we can call with
npm. Add the
This script calls webpack and passes in the
webpack.config.js configuration file.
We’re using the local installation of webpack and the webpack-dev-server in these scripts. This allows each project to use its own individual version, and is what is recommended by the webpack documentation. If you’d prefer to use the global version, install it globally with
npm install --global webpack and use the command
webpack --config webpack.config.js to run.
When you run the build command,
you should see some output from webpack starting with something like this:
app.js bundle and
index.html file will be output into the
Run the development server
webpack-dev-server to serve a development build and see our app in action.
start script to
package.json to run the development server. Set the config file via the
--config flag. Use the
--open flag to open the app in a browser when the command is executed.
Tell the development server to serve files the
dist folder. Add this at the bottom of
Finally, we can run the app!
You should see your content served at
localhost:8080, and you should see the “Hello World!” message when you open up the browser console.
Add CesiumJS to a webpack app
cesium module from npm and add it to
Configure CesiumJS in webpack
First, define where CesiumJS is. This tutorial uses the source code, so webpack can include individual models and trace the dependencies. Alternatively, you can use the built (minified or unminified) version of CesiumJS. However, the modules are already combined and optimized, which gives us less flexibility.
Add the following to the top of
Add the following options to the configuration object to resolve some quirks with how webpack compiles CesiumJS.
output.sourcePrefix: ''overrides the webpack default for adding a
\ttab character before each line. CesiumJS has some multiline strings, so we need to override this default with an empty prefix
amd.toUrlUndefined: truetells CesiumJS that the version of AMD webpack uses to evaluate
requirestatements is not compliant with the standard
node.fs: 'empty'resolves some third-party usage of the
fsmodule, which is targeted for use in a Node environment rather than the browser.
cesium alias alias so we can reference it in our app code.
Manage CesiumJS static files
Lastly, make sure the static CesiumJS asset, widget, and web worker files are served and loaded correctly.
copy-webpack-plugin to copy static files to the
dist directory as part of the build process.
Require it near the top of our
Add the following to the
This copies the
Widgets directories, and the built web worker scripts.
If you are using a fork of the CesiumJS repo, the
Build folder will not already exist. Run
npm run release to produce the build output. For more information, see the Cesium Build Guide.
Define an environment variable that tells CesiumJS the base URL for loading static files using the webpack
plugins array will now look like this:
Require CesiumJS modules in our app
There are a few ways we can require CesiumJS modules within our application. You can use either CommonJS syntax or ES6
You can import the whole CesiumJS library or require only the specific modules you need. Including modules will result in webpack compiling only those modules and their dependencies in your bundle instead of the entire library.
To require all of CesiumJS:
To require an individual module:
ES6 style import
To require all of CesiumJS:
To require an individual module:
Requiring asset files
Create a new file,
src/css/main.css, for styling our app:
Create a div for the CesiumJS Viewer in the
index.html body. Replace
<p>Hello World!</p> with this div:
Delete the contents of
index.js and include
Cesium and our CSS files:
Add this line to create the
Run the app with
npm start to see the Viewer in your browser!
Advanced webpack configurations
webpack can be leveraged in many more ways to increase performance, decrease your bundle size, and perform additional or complex build steps. Here we’ll discuss a few configuration options relevant to using the CesiumJS library.
Our configuration for an optimal production Cesium webpack build can be found in our example repo at
webpack packages CesiumJS in the same chunk as our application by default, which results in a large file. We can split CesiumJS into its own bundle and improve our app performance using the
CommonChunksPlugin. If you end up creating multiple chunks for your app, they can all reference one common
Add the plugin to your
webpack.config.js file, and specify the rule for breaking out CesiumJS modules:
Enable source maps
Source maps allow webpack to trace errors back to the original content. They offer more or less detailed debugging information in exchange for compiling speed. We recommend using the
Source maps are not recommended for production.
There are developer errors and warnings in the CesiumJS source code that are removed from our minified release builds. Since there’s no built-in webpack way to remove these warnings, we’ll use the
Install the package:
Include the loader in
debug set to
Uglify and minify
uglifyjs-webpack-plugin to uglify the CesiumJS source.
Require it in your config file.
Include it in the list of plugins.
minimize option on the
css-loader to minify the CSS.
The official cesium-webpack-example repo contains the minimal webpack configuration, the hello world code covered in this tutorial, and instructions for optional code configurations.
For a tour of CesiumJS feature to include in your new app, see the Cesium Workshop Tutorial.