From f0ec64f0d4c06dae4885bca120066050c396517e Mon Sep 17 00:00:00 2001 From: Josh <8007967+jjspace@users.noreply.github.com> Date: Tue, 9 Jan 2024 11:49:40 -0500 Subject: [PATCH 01/10] move code to webpack 5 directory --- .gitignore | 4 +- .vscode/settings.json | 3 + .eslintignore => webpack-5/.eslintignore | 0 .eslintrc.json => webpack-5/.eslintrc.json | 0 .npmignore => webpack-5/.npmignore | 0 .prettierignore => webpack-5/.prettierignore | 2 +- .prettierrc => webpack-5/.prettierrc | 0 webpack-5/README.md | 90 +++++++++++++++++++ package.json => webpack-5/package.json | 0 {src => webpack-5/src}/.eslintrc.json | 0 {src => webpack-5/src}/css/main.css | 0 {src => webpack-5/src}/index.html | 0 {src => webpack-5/src}/index.js | 2 +- .../webpack.config.js | 1 - 14 files changed, 97 insertions(+), 5 deletions(-) create mode 100644 .vscode/settings.json rename .eslintignore => webpack-5/.eslintignore (100%) rename .eslintrc.json => webpack-5/.eslintrc.json (100%) rename .npmignore => webpack-5/.npmignore (100%) rename .prettierignore => webpack-5/.prettierignore (95%) rename .prettierrc => webpack-5/.prettierrc (100%) create mode 100644 webpack-5/README.md rename package.json => webpack-5/package.json (100%) rename {src => webpack-5/src}/.eslintrc.json (100%) rename {src => webpack-5/src}/css/main.css (100%) rename {src => webpack-5/src}/index.html (100%) rename {src => webpack-5/src}/index.js (96%) rename webpack.config.js => webpack-5/webpack.config.js (97%) diff --git a/.gitignore b/.gitignore index 2f72fe4..3810308 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ -/dist/ -/node_modules/ +dist/ +node_modules/ package-lock.json .DS_Store .eslintcache diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..3ad1c2f --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "prettier.singleQuote": false +} diff --git a/.eslintignore b/webpack-5/.eslintignore similarity index 100% rename from .eslintignore rename to webpack-5/.eslintignore diff --git a/.eslintrc.json b/webpack-5/.eslintrc.json similarity index 100% rename from .eslintrc.json rename to webpack-5/.eslintrc.json diff --git a/.npmignore b/webpack-5/.npmignore similarity index 100% rename from .npmignore rename to webpack-5/.npmignore diff --git a/.prettierignore b/webpack-5/.prettierignore similarity index 95% rename from .prettierignore rename to webpack-5/.prettierignore index eab7d5e..2105561 100644 --- a/.prettierignore +++ b/webpack-5/.prettierignore @@ -5,7 +5,7 @@ # Unignore directories (to all depths) and unignore code and style files in these directories !.github/**/ !.vscode/**/ -!src/**/ +!/src/**/ !doc/**/ !**/*.js diff --git a/.prettierrc b/webpack-5/.prettierrc similarity index 100% rename from .prettierrc rename to webpack-5/.prettierrc diff --git a/webpack-5/README.md b/webpack-5/README.md new file mode 100644 index 0000000..abc2e05 --- /dev/null +++ b/webpack-5/README.md @@ -0,0 +1,90 @@ +# cesium-webpack-example + +A minimal recommended setup for an applications using [Cesium](https://cesium.com) with [Webpack](https://webpack.js.org/concepts/). + +[![Build Status](https://travis-ci.org/CesiumGS/cesium-webpack-example.svg?branch=using-custom-loader)](https://travis-ci.org/CesiumGS/cesium-webpack-example) + +## Running this application + +```sh +npm install +npm start +``` + +Navigate to `localhost:8080`. + +### Available scripts + +- `npm start` - Runs a webpack build with `webpack.config.js` and starts a development server +- `npm run build` - Runs a webpack build with `webpack.config.js` + +## Requiring Cesium in your application + +We recommend [importing named exports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) from the Cesium ES module, via the `import` keyword. This allows webpack to [tree shake](https://webpack.js.org/guides/tree-shaking/) your application automatically. + +### Import named modules from Cesium + +```js +import { Color } from "cesium"; +var c = Color.fromRandom(); +``` + +### Import Cesium static asset files + +```js +import "cesium/Build/Cesium/Widgets/widgets.css"; +``` + +## Cesium sub-packages + +CesiumJS requires a few static files to be hosted on your server, like web workers and SVG icons. This example is set up to copy these directories already if you install the whole `cesium` package. However if you only install `@cesium/engine` then you should change the paths in `webpack.config.js` to the ones below: + +```js +new CopyWebpackPlugin({ + patterns: [ + { from: 'node_modules/@cesium/engine/Build/Workers', to: `${cesiumBaseUrl}/Workers` }, + { from: 'node_modules/@cesium/engine/Build/ThirdParty', to: `${cesiumBaseUrl}/ThirdParty` }, + { from: 'node_modules/@cesium/engine/Source/Assets', to: `${cesiumBaseUrl}/Assets` }, + ], +}), +``` + +## Removing pragmas + +To remove pragmas such as a traditional Cesium release build, use the [`strip-pragma-loader`](https://www.npmjs.com/package/strip-pragma-loader). + +Install the plugin with npm, + +```sh +npm install strip-pragma-loader --save-dev +``` + +and include the loader in `module.rules` with `debug` set to `false`. + +```js +rules: [ + { + test: /\.js$/, + enforce: "pre", + include: path.resolve(__dirname, cesiumSource), + use: [ + { + loader: "strip-pragma-loader", + options: { + pragmas: { + debug: false, + }, + }, + }, + ], + }, +]; +``` + +## Contributions + +Pull requests are appreciated. Please use the same [Contributor License Agreement (CLA)](https://github.com/CesiumGS/cesium/blob/master/CONTRIBUTING.md) used for [Cesium](https://cesium.com/). + +--- + +Developed by the Cesium team. diff --git a/package.json b/webpack-5/package.json similarity index 100% rename from package.json rename to webpack-5/package.json diff --git a/src/.eslintrc.json b/webpack-5/src/.eslintrc.json similarity index 100% rename from src/.eslintrc.json rename to webpack-5/src/.eslintrc.json diff --git a/src/css/main.css b/webpack-5/src/css/main.css similarity index 100% rename from src/css/main.css rename to webpack-5/src/css/main.css diff --git a/src/index.html b/webpack-5/src/index.html similarity index 100% rename from src/index.html rename to webpack-5/src/index.html diff --git a/src/index.js b/webpack-5/src/index.js similarity index 96% rename from src/index.js rename to webpack-5/src/index.js index ea11931..d495881 100644 --- a/src/index.js +++ b/webpack-5/src/index.js @@ -6,7 +6,7 @@ import { createOsmBuildingsAsync, } from "cesium"; import "cesium/Build/Cesium/Widgets/widgets.css"; -import "../src/css/main.css"; +import "./css/main.css"; // CesiumJS has a default access token built in but it's not meant for active use. // please set your own access token can be found at: https://cesium.com/ion/tokens. diff --git a/webpack.config.js b/webpack-5/webpack.config.js similarity index 97% rename from webpack.config.js rename to webpack-5/webpack.config.js index d8ac689..cd23b5d 100644 --- a/webpack.config.js +++ b/webpack-5/webpack.config.js @@ -1,6 +1,5 @@ "use strict"; -// The path to the CesiumJS source code const CopyWebpackPlugin = require("copy-webpack-plugin"); const path = require("path"); const webpack = require("webpack"); From 3347c439b7482ed19482e5e834c5d118dd938009 Mon Sep 17 00:00:00 2001 From: Josh <8007967+jjspace@users.noreply.github.com> Date: Tue, 9 Jan 2024 11:49:59 -0500 Subject: [PATCH 02/10] small doc updates --- README.md | 4 +++- doc/cesium.png | Bin 4664 -> 0 bytes 2 files changed, 3 insertions(+), 1 deletion(-) delete mode 100644 doc/cesium.png diff --git a/README.md b/README.md index abc2e05..1987371 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,12 @@ A minimal recommended setup for an applications using [Cesium](https://cesium.com) with [Webpack](https://webpack.js.org/concepts/). -[![Build Status](https://travis-ci.org/CesiumGS/cesium-webpack-example.svg?branch=using-custom-loader)](https://travis-ci.org/CesiumGS/cesium-webpack-example) +Jump to the [Webpack 5](./webpack-5/) directory for the most up to date example. We also provide a [Webpack 4](./webpack-4/) example if you are still on the older version. ## Running this application ```sh +# switch to the correspoding webpack-4 or webpack-5 directory npm install npm start ``` @@ -17,6 +18,7 @@ Navigate to `localhost:8080`. - `npm start` - Runs a webpack build with `webpack.config.js` and starts a development server - `npm run build` - Runs a webpack build with `webpack.config.js` +- `npm run start:built` - Hosts a static server of the built assets to demonstrate running the full built code ## Requiring Cesium in your application diff --git a/doc/cesium.png b/doc/cesium.png deleted file mode 100644 index 32db61698f08c8d7ef37b002e0ab294df1c34a37..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 4664 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 Date: Tue, 9 Jan 2024 12:10:18 -0500 Subject: [PATCH 03/10] Add webpack 4 example --- webpack-4/package.json | 45 ++++++++++++++++++ webpack-4/src/.eslintrc.json | 11 +++++ webpack-4/src/css/main.css | 9 ++++ webpack-4/src/index.html | 9 ++++ webpack-4/src/index.js | 26 ++++++++++ webpack-4/webpack.config.js | 92 ++++++++++++++++++++++++++++++++++++ webpack-5/package.json | 2 +- 7 files changed, 193 insertions(+), 1 deletion(-) create mode 100644 webpack-4/package.json create mode 100644 webpack-4/src/.eslintrc.json create mode 100644 webpack-4/src/css/main.css create mode 100644 webpack-4/src/index.html create mode 100644 webpack-4/src/index.js create mode 100644 webpack-4/webpack.config.js diff --git a/webpack-4/package.json b/webpack-4/package.json new file mode 100644 index 0000000..d892d05 --- /dev/null +++ b/webpack-4/package.json @@ -0,0 +1,45 @@ +{ + "name": "cesiumjs-webpack-example", + "version": "1.0.0", + "description": "The minimal recommended setup for an app using Cesium with Webpack.", + "homepage": "https://cesium.com/platform/cesiumjs/", + "license": "Apache-2.0", + "author": { + "name": "Cesium GS, Inc.", + "url": "https://cesium.com" + }, + "keywords": [ + "cesium", + "CesiumJS", + "webpack", + "example" + ], + "repository": { + "type": "git", + "url": "https://github.com/CesiumGS/cesium-webpack-example.git" + }, + "main": "index.js", + "scripts": { + "build": "webpack --config webpack.config.js", + "start": "webpack serve --config webpack.config.js", + "start:built": "npx http-server -a localhost -p 8080 dist/" + }, + "devDependencies": { + "@babel/core": "^7.23.7", + "@babel/plugin-transform-optional-chaining": "^7.23.4", + "@babel/preset-env": "^7.23.7", + "@open-wc/webpack-import-meta-loader": "^0.4.7", + "babel-loader": "^8.3.0", + "copy-webpack-plugin": "^6.4.1", + "css-loader": "^5.2.7", + "file-loader": "^6.2.0", + "html-webpack-plugin": "^4.5.2", + "style-loader": "^2.0.0", + "webpack": "^4.47.0", + "webpack-cli": "^4.10.0", + "webpack-dev-server": "^4.15.1" + }, + "dependencies": { + "cesium": "^1.113.0" + } +} diff --git a/webpack-4/src/.eslintrc.json b/webpack-4/src/.eslintrc.json new file mode 100644 index 0000000..e5cb154 --- /dev/null +++ b/webpack-4/src/.eslintrc.json @@ -0,0 +1,11 @@ +{ + "root": true, + "extends": ["cesium/browser"], + "plugins": ["html", "es"], + "parserOptions": { + "ecmaVersion": 2023 + }, + "rules": { + "no-unused-vars": ["error", { "vars": "all", "args": "none" }] + } +} diff --git a/webpack-4/src/css/main.css b/webpack-4/src/css/main.css new file mode 100644 index 0000000..f9433f9 --- /dev/null +++ b/webpack-4/src/css/main.css @@ -0,0 +1,9 @@ +html, +body, +#cesiumContainer { + width: 100%; + height: 100%; + margin: 0; + padding: 0; + overflow: hidden; +} diff --git a/webpack-4/src/index.html b/webpack-4/src/index.html new file mode 100644 index 0000000..1f4d96c --- /dev/null +++ b/webpack-4/src/index.html @@ -0,0 +1,9 @@ + + + + + + +
+ + diff --git a/webpack-4/src/index.js b/webpack-4/src/index.js new file mode 100644 index 0000000..d20d561 --- /dev/null +++ b/webpack-4/src/index.js @@ -0,0 +1,26 @@ +import { Viewer, Cartesian3, Math, Terrain, createOsmBuildingsAsync } from "cesium"; +import "cesium/Build/Cesium/Widgets/widgets.css"; +import "./css/main.css"; + +// CesiumJS has a default access token built in but it's not meant for active use. +// please set your own access token can be found at: https://cesium.com/ion/tokens. +// Ion.defaultAccessToken = "YOUR TOKEN HERE"; + +// Initialize the Cesium Viewer in the HTML element with the `cesiumContainer` ID. +const viewer = new Viewer("cesiumContainer", { + terrain: Terrain.fromWorldTerrain(), +}); + +// Add Cesium OSM Buildings, a global 3D buildings layer. +createOsmBuildingsAsync().then((buildingTileset) => { + viewer.scene.primitives.add(buildingTileset); +}); + +// Fly the camera to San Francisco at the given longitude, latitude, and height. +viewer.camera.flyTo({ + destination: Cartesian3.fromDegrees(-122.4175, 37.655, 400), + orientation: { + heading: Math.toRadians(0.0), + pitch: Math.toRadians(-15.0), + }, +}); diff --git a/webpack-4/webpack.config.js b/webpack-4/webpack.config.js new file mode 100644 index 0000000..7616613 --- /dev/null +++ b/webpack-4/webpack.config.js @@ -0,0 +1,92 @@ +"use strict"; + +const CopyWebpackPlugin = require("copy-webpack-plugin"); +const path = require("path"); +const webpack = require("webpack"); +const HtmlWebpackPlugin = require("html-webpack-plugin"); + +const cesiumSource = "node_modules/cesium/Build/Cesium"; +// this is the base url for static files that CesiumJS needs to load +// Not required but if it's set remember to update CESIUM_BASE_URL as shown below +const cesiumBaseUrl = "cesiumStatic"; + +module.exports = { + entry: "./src/index.js", + output: { + filename: "app.js", + path: path.resolve(__dirname, "dist"), + }, + // resolve: { + // fallback: { https: false, zlib: false, http: false, url: false }, + // mainFiles: ["index", "Cesium"], + // }, + module: { + unknownContextCritical: false, + rules: [ + { + test: /\.(?:js|mjs|cjs)$/, + exclude: { + and: [/node_modules/], // Exclude libraries in node_modules ... + not: [/cesium/], // Except Cesium because it uses modern syntax + }, + use: [ + { + loader: "babel-loader", + options: { + presets: [["@babel/preset-env", { targets: "defaults, not ie 11" }]], + plugins: ["@babel/plugin-transform-optional-chaining"], + }, + }, + // Babel understands import.meta but Webpack doesn't + // can't find a way to tell babel not to output it so we need another loader + // that can understand it and translate into Webpack's representation + // https://www.npmjs.com/package/@open-wc/webpack-import-meta-loader + // TODO: but then we get static dependency errors about `require` in buildModuleUrl instead + require.resolve("@open-wc/webpack-import-meta-loader"), + ], + }, + { + test: /\.css/, + use: ["style-loader", "css-loader"], + }, + { + test: /\.(png|gif|jpg|jpeg|svg|xml|json)$/, + use: ["file-loader"], + }, + ], + }, + plugins: [ + new HtmlWebpackPlugin({ + template: "./src/index.html", + }), + // Copy Cesium Assets, Widgets, and Workers to a static directory + new CopyWebpackPlugin({ + patterns: [ + { + from: path.join(cesiumSource, "Workers"), + to: `${cesiumBaseUrl}/Workers`, + }, + { + from: path.join(cesiumSource, "ThirdParty"), + to: `${cesiumBaseUrl}/ThirdParty`, + }, + { + from: path.join(cesiumSource, "Assets"), + to: `${cesiumBaseUrl}/Assets`, + }, + { + from: path.join(cesiumSource, "Widgets"), + to: `${cesiumBaseUrl}/Widgets`, + }, + ], + }), + new webpack.DefinePlugin({ + // Define relative base path in cesium for loading assets + CESIUM_BASE_URL: JSON.stringify(cesiumBaseUrl), + }), + ], + devServer: { + static: "./dist", + }, + mode: "development", +}; diff --git a/webpack-5/package.json b/webpack-5/package.json index f015420..bb6ecaf 100644 --- a/webpack-5/package.json +++ b/webpack-5/package.json @@ -1,7 +1,7 @@ { "name": "cesiumjs-webpack-example", "version": "1.0.0", - "description": "The minimal recomended setup for an app using Cesium with Webpack.", + "description": "The minimal recommended setup for an app using Cesium with Webpack.", "homepage": "https://cesium.com/platform/cesiumjs/", "license": "Apache-2.0", "author": { From f8306a20b6e4e17ff37924a6329111fe83be700a Mon Sep 17 00:00:00 2001 From: Josh <8007967+jjspace@users.noreply.github.com> Date: Tue, 9 Jan 2024 12:14:38 -0500 Subject: [PATCH 04/10] add prettier and linting --- webpack-4/.eslintignore | 1 + webpack-4/.eslintrc.json | 4 ++++ webpack-4/.npmignore | 1 + webpack-4/.prettierignore | 15 +++++++++++++++ webpack-4/.prettierrc | 1 + webpack-4/package.json | 10 +++++++++- webpack-4/src/index.js | 8 +++++++- webpack-4/webpack.config.js | 4 +++- 8 files changed, 41 insertions(+), 3 deletions(-) create mode 100644 webpack-4/.eslintignore create mode 100644 webpack-4/.eslintrc.json create mode 100644 webpack-4/.npmignore create mode 100644 webpack-4/.prettierignore create mode 100644 webpack-4/.prettierrc diff --git a/webpack-4/.eslintignore b/webpack-4/.eslintignore new file mode 100644 index 0000000..06c5e16 --- /dev/null +++ b/webpack-4/.eslintignore @@ -0,0 +1 @@ +dist/** diff --git a/webpack-4/.eslintrc.json b/webpack-4/.eslintrc.json new file mode 100644 index 0000000..94b4f97 --- /dev/null +++ b/webpack-4/.eslintrc.json @@ -0,0 +1,4 @@ +{ + "root": true, + "extends": ["cesium/node"] +} diff --git a/webpack-4/.npmignore b/webpack-4/.npmignore new file mode 100644 index 0000000..f84c843 --- /dev/null +++ b/webpack-4/.npmignore @@ -0,0 +1 @@ +webpack.config.js \ No newline at end of file diff --git a/webpack-4/.prettierignore b/webpack-4/.prettierignore new file mode 100644 index 0000000..2105561 --- /dev/null +++ b/webpack-4/.prettierignore @@ -0,0 +1,15 @@ + +# Ignore everything +* + +# Unignore directories (to all depths) and unignore code and style files in these directories +!.github/**/ +!.vscode/**/ +!/src/**/ +!doc/**/ + +!**/*.js +!**/*.css +!**/*.html +!**/*.md +!**/*.json diff --git a/webpack-4/.prettierrc b/webpack-4/.prettierrc new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/webpack-4/.prettierrc @@ -0,0 +1 @@ +{} diff --git a/webpack-4/package.json b/webpack-4/package.json index d892d05..8072835 100644 --- a/webpack-4/package.json +++ b/webpack-4/package.json @@ -22,7 +22,10 @@ "scripts": { "build": "webpack --config webpack.config.js", "start": "webpack serve --config webpack.config.js", - "start:built": "npx http-server -a localhost -p 8080 dist/" + "start:built": "npx http-server -a localhost -p 8080 dist/", + "eslint": "eslint \"./**/*.js\" \"./**/*.html\" --cache --quiet", + "prettier": "prettier --write --no-config \"**/*\"", + "prettier-check": "prettier --check --no-config \"**/*\"" }, "devDependencies": { "@babel/core": "^7.23.7", @@ -32,8 +35,13 @@ "babel-loader": "^8.3.0", "copy-webpack-plugin": "^6.4.1", "css-loader": "^5.2.7", + "eslint": "^8.56.0", + "eslint-config-cesium": "^10.0.2", + "eslint-plugin-es": "^4.1.0", + "eslint-plugin-html": "^7.1.0", "file-loader": "^6.2.0", "html-webpack-plugin": "^4.5.2", + "prettier": "^3.1.1", "style-loader": "^2.0.0", "webpack": "^4.47.0", "webpack-cli": "^4.10.0", diff --git a/webpack-4/src/index.js b/webpack-4/src/index.js index d20d561..103f912 100644 --- a/webpack-4/src/index.js +++ b/webpack-4/src/index.js @@ -1,4 +1,10 @@ -import { Viewer, Cartesian3, Math, Terrain, createOsmBuildingsAsync } from "cesium"; +import { + Viewer, + Cartesian3, + Math, + Terrain, + createOsmBuildingsAsync, +} from "cesium"; import "cesium/Build/Cesium/Widgets/widgets.css"; import "./css/main.css"; diff --git a/webpack-4/webpack.config.js b/webpack-4/webpack.config.js index 7616613..11eb833 100644 --- a/webpack-4/webpack.config.js +++ b/webpack-4/webpack.config.js @@ -33,7 +33,9 @@ module.exports = { { loader: "babel-loader", options: { - presets: [["@babel/preset-env", { targets: "defaults, not ie 11" }]], + presets: [ + ["@babel/preset-env", { targets: "defaults, not ie 11" }], + ], plugins: ["@babel/plugin-transform-optional-chaining"], }, }, From 7e93bdc61acd79447797cc1976a47ea465d1ac90 Mon Sep 17 00:00:00 2001 From: Josh <8007967+jjspace@users.noreply.github.com> Date: Tue, 9 Jan 2024 12:16:13 -0500 Subject: [PATCH 05/10] fix github actions --- .github/workflows/main.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 35b397b..cc3dae3 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -6,7 +6,11 @@ jobs: strategy: matrix: node: [18, 20] + webpack-dir: [webpack-4, webpack-5] name: Node ${{ matrix.node }} + defaults: + run: + working-directory: ${{ matrix.webpack-dir }} steps: - uses: actions/checkout@v3 - name: install node ${{ matrix.node }} From 4cb1f0a60322ddf71d3478c6d37aae36481a96ba Mon Sep 17 00:00:00 2001 From: Josh <8007967+jjspace@users.noreply.github.com> Date: Tue, 9 Jan 2024 12:17:51 -0500 Subject: [PATCH 06/10] better gha names --- .github/workflows/main.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index cc3dae3..2e99037 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -7,7 +7,7 @@ jobs: matrix: node: [18, 20] webpack-dir: [webpack-4, webpack-5] - name: Node ${{ matrix.node }} + name: Node ${{ matrix.node }} - ${{ matrix.webpack-dir }} defaults: run: working-directory: ${{ matrix.webpack-dir }} From f058898935678ef70450b0c8f6f03c626ab9c89c Mon Sep 17 00:00:00 2001 From: Josh <8007967+jjspace@users.noreply.github.com> Date: Wed, 10 Jan 2024 16:14:01 -0500 Subject: [PATCH 07/10] restructure packages and linting --- .eslintignore | 1 + webpack-4/.eslintrc.json => .eslintrc.json | 0 webpack-5/.prettierignore => .prettierignore | 4 +- README.md | 13 ++++-- package.json | 46 ++++++++++++++++++++ webpack-4/.eslintignore | 1 - webpack-4/.prettierignore | 15 ------- webpack-4/.prettierrc | 1 - webpack-4/package.json | 18 +++----- webpack-5/.eslintignore | 1 - webpack-5/.eslintrc.json | 4 -- webpack-5/.prettierrc | 1 - webpack-5/package.json | 23 +++------- 13 files changed, 69 insertions(+), 59 deletions(-) create mode 100644 .eslintignore rename webpack-4/.eslintrc.json => .eslintrc.json (100%) rename webpack-5/.prettierignore => .prettierignore (83%) create mode 100644 package.json delete mode 100644 webpack-4/.eslintignore delete mode 100644 webpack-4/.prettierignore delete mode 100644 webpack-4/.prettierrc delete mode 100644 webpack-5/.eslintignore delete mode 100644 webpack-5/.eslintrc.json delete mode 100644 webpack-5/.prettierrc diff --git a/.eslintignore b/.eslintignore new file mode 100644 index 0000000..3847424 --- /dev/null +++ b/.eslintignore @@ -0,0 +1 @@ +*/dist/** diff --git a/webpack-4/.eslintrc.json b/.eslintrc.json similarity index 100% rename from webpack-4/.eslintrc.json rename to .eslintrc.json diff --git a/webpack-5/.prettierignore b/.prettierignore similarity index 83% rename from webpack-5/.prettierignore rename to .prettierignore index 2105561..2fd774f 100644 --- a/webpack-5/.prettierignore +++ b/.prettierignore @@ -5,8 +5,10 @@ # Unignore directories (to all depths) and unignore code and style files in these directories !.github/**/ !.vscode/**/ -!/src/**/ !doc/**/ +!webpack-4/**/ +!webpack-5/**/ +!src/**/ !**/*.js !**/*.css diff --git a/README.md b/README.md index 1987371..b764772 100644 --- a/README.md +++ b/README.md @@ -9,16 +9,19 @@ Jump to the [Webpack 5](./webpack-5/) directory for the most up to date example. ```sh # switch to the correspoding webpack-4 or webpack-5 directory npm install -npm start +npm run start-4 +npm run start-5 ``` Navigate to `localhost:8080`. ### Available scripts -- `npm start` - Runs a webpack build with `webpack.config.js` and starts a development server -- `npm run build` - Runs a webpack build with `webpack.config.js` -- `npm run start:built` - Hosts a static server of the built assets to demonstrate running the full built code +- `npm run start-4` - Run the Webpack 4 example +- `npm run build-4` - Build the Webpack 4 example +- `npm run start-5` - Run the Webpack 4 example +- `npm run build-5` - Build the Webpack 4 example +- `npm run eslint`, `npm run prettier`, `npm run prettier-check` - Lint this project to maintain code style ## Requiring Cesium in your application @@ -90,3 +93,5 @@ Pull requests are appreciated. Please use the same [Contributor License Agreemen --- Developed by the Cesium team. + +Even though this project has nested package.json projects we are not using `npm` workspaces to preserve a more "stand-alone" nature for each example. This allows other developers to copy the sub-directory and use it as-is for a new project. diff --git a/package.json b/package.json new file mode 100644 index 0000000..b705455 --- /dev/null +++ b/package.json @@ -0,0 +1,46 @@ +{ + "name": "cesiumjs-webpack-example", + "version": "1.0.0", + "description": "The minimal recommended setup for an app using Cesium with Webpack.", + "homepage": "https://cesium.com/platform/cesiumjs/", + "license": "Apache-2.0", + "author": { + "name": "Cesium GS, Inc.", + "url": "https://cesium.com" + }, + "keywords": [ + "cesium", + "CesiumJS", + "webpack", + "example" + ], + "repository": { + "type": "git", + "url": "https://github.com/CesiumGS/cesium-webpack-example.git" + }, + "scripts": { + "prepare": "husky install", + "postinstall": "cd webpack-4 && npm install && cd ../webpack-5 && npm install", + "eslint": "eslint \"./**/*.js\" \"./**/*.html\" --cache --quiet", + "prettier": "prettier --write --no-config \"**/*\"", + "prettier-check": "prettier --check --no-config \"**/*\"", + "start-4": "cd webpack-4 && npm run start", + "build-4": "cd webpack-4 && npm run build", + "start-5": "cd webpack-5 && npm run start", + "build-5": "cd webpack-5 && npm run build" + }, + "devDependencies": { + "eslint": "^8.56.0", + "eslint-config-cesium": "^10.0.2", + "eslint-plugin-es": "^4.1.0", + "eslint-plugin-html": "^7.1.0", + "husky": "^8.0.3", + "prettier": "^3.1.1" + }, + "lint-staged": { + "*.{js,html}": [ + "eslint --cache --quiet", + "prettier --write --no-config" + ] + } +} diff --git a/webpack-4/.eslintignore b/webpack-4/.eslintignore deleted file mode 100644 index 06c5e16..0000000 --- a/webpack-4/.eslintignore +++ /dev/null @@ -1 +0,0 @@ -dist/** diff --git a/webpack-4/.prettierignore b/webpack-4/.prettierignore deleted file mode 100644 index 2105561..0000000 --- a/webpack-4/.prettierignore +++ /dev/null @@ -1,15 +0,0 @@ - -# Ignore everything -* - -# Unignore directories (to all depths) and unignore code and style files in these directories -!.github/**/ -!.vscode/**/ -!/src/**/ -!doc/**/ - -!**/*.js -!**/*.css -!**/*.html -!**/*.md -!**/*.json diff --git a/webpack-4/.prettierrc b/webpack-4/.prettierrc deleted file mode 100644 index 0967ef4..0000000 --- a/webpack-4/.prettierrc +++ /dev/null @@ -1 +0,0 @@ -{} diff --git a/webpack-4/package.json b/webpack-4/package.json index 8072835..b16f39c 100644 --- a/webpack-4/package.json +++ b/webpack-4/package.json @@ -1,5 +1,5 @@ { - "name": "cesiumjs-webpack-example", + "name": "cesiumjs-webpack-4-example", "version": "1.0.0", "description": "The minimal recommended setup for an app using Cesium with Webpack.", "homepage": "https://cesium.com/platform/cesiumjs/", @@ -22,10 +22,10 @@ "scripts": { "build": "webpack --config webpack.config.js", "start": "webpack serve --config webpack.config.js", - "start:built": "npx http-server -a localhost -p 8080 dist/", - "eslint": "eslint \"./**/*.js\" \"./**/*.html\" --cache --quiet", - "prettier": "prettier --write --no-config \"**/*\"", - "prettier-check": "prettier --check --no-config \"**/*\"" + "start:built": "npx http-server -a localhost -p 8080 dist/" + }, + "dependencies": { + "cesium": "^1.113.0" }, "devDependencies": { "@babel/core": "^7.23.7", @@ -35,19 +35,11 @@ "babel-loader": "^8.3.0", "copy-webpack-plugin": "^6.4.1", "css-loader": "^5.2.7", - "eslint": "^8.56.0", - "eslint-config-cesium": "^10.0.2", - "eslint-plugin-es": "^4.1.0", - "eslint-plugin-html": "^7.1.0", "file-loader": "^6.2.0", "html-webpack-plugin": "^4.5.2", - "prettier": "^3.1.1", "style-loader": "^2.0.0", "webpack": "^4.47.0", "webpack-cli": "^4.10.0", "webpack-dev-server": "^4.15.1" - }, - "dependencies": { - "cesium": "^1.113.0" } } diff --git a/webpack-5/.eslintignore b/webpack-5/.eslintignore deleted file mode 100644 index 06c5e16..0000000 --- a/webpack-5/.eslintignore +++ /dev/null @@ -1 +0,0 @@ -dist/** diff --git a/webpack-5/.eslintrc.json b/webpack-5/.eslintrc.json deleted file mode 100644 index 94b4f97..0000000 --- a/webpack-5/.eslintrc.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "root": true, - "extends": ["cesium/node"] -} diff --git a/webpack-5/.prettierrc b/webpack-5/.prettierrc deleted file mode 100644 index 0967ef4..0000000 --- a/webpack-5/.prettierrc +++ /dev/null @@ -1 +0,0 @@ -{} diff --git a/webpack-5/package.json b/webpack-5/package.json index bb6ecaf..7efbf14 100644 --- a/webpack-5/package.json +++ b/webpack-5/package.json @@ -1,5 +1,5 @@ { - "name": "cesiumjs-webpack-example", + "name": "cesiumjs-webpack-5-example", "version": "1.0.0", "description": "The minimal recommended setup for an app using Cesium with Webpack.", "homepage": "https://cesium.com/platform/cesiumjs/", @@ -22,31 +22,18 @@ "scripts": { "build": "webpack --config webpack.config.js", "start": "webpack serve --config webpack.config.js", - "start:built": "npx http-server -a localhost -p 8080 dist/", - "eslint": "eslint \"./**/*.js\" \"./**/*.html\" --cache --quiet", - "prettier": "prettier --write --no-config \"**/*\"", - "prettier-check": "prettier --check --no-config \"**/*\"" + "start:built": "npx http-server -a localhost -p 8080 dist/" + }, + "dependencies": { + "cesium": "^1.113.0" }, "devDependencies": { - "cesium": "^1.113.0", "copy-webpack-plugin": "^9.1.0", "css-loader": "^6.8.1", - "eslint": "^8.56.0", - "eslint-config-cesium": "^10.0.2", - "eslint-plugin-es": "^4.1.0", - "eslint-plugin-html": "^7.1.0", "html-webpack-plugin": "^5.6.0", - "husky": "^8.0.3", - "prettier": "^3.1.1", "style-loader": "^3.3.3", "webpack": "^5.89.0", "webpack-cli": "^4.10.0", "webpack-dev-server": "^4.15.1" - }, - "lint-staged": { - "*.{js,cjs,html}": [ - "eslint --cache --quiet", - "prettier --write --no-config" - ] } } From bb9d2501f036ff77eee6ae7e15f87ccaea8aa458 Mon Sep 17 00:00:00 2001 From: Josh <8007967+jjspace@users.noreply.github.com> Date: Wed, 10 Jan 2024 16:27:44 -0500 Subject: [PATCH 08/10] fix gha again --- .github/workflows/lint.yml | 18 ++++++++++++++++++ .github/workflows/main.yml | 4 ---- 2 files changed, 18 insertions(+), 4 deletions(-) create mode 100644 .github/workflows/lint.yml diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 0000000..2c1a54b --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,18 @@ +name: lint +on: push +jobs: + build: + runs-on: ubuntu-latest + name: Lint/Format check + steps: + - uses: actions/checkout@v3 + - name: install node 20 + uses: actions/setup-node@v3 + with: + node-version: 20 + - name: install + run: npm install + - name: lint *.js + run: npm run eslint + - name: format code + run: npm run prettier-check diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 2e99037..c92ed8b 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -19,9 +19,5 @@ jobs: node-version: ${{ matrix.node }} - name: install run: npm install - - name: lint *.js - run: npm run eslint - - name: format code - run: npm run prettier-check - name: build run: npm run build From bc00e97f4d736a016e2a580615643a1f54f7f08c Mon Sep 17 00:00:00 2001 From: Josh <8007967+jjspace@users.noreply.github.com> Date: Thu, 11 Jan 2024 12:44:33 -0500 Subject: [PATCH 09/10] pr comments --- .prettierrc | 1 + .vscode/settings.json | 3 -- README.md | 42 +++++++++++---- webpack-4/README.md | 105 ++++++++++++++++++++++++++++++++++++ webpack-4/package.json | 2 +- webpack-4/webpack.config.js | 11 ++-- webpack-5/README.md | 25 +++++++-- webpack-5/package.json | 2 +- 8 files changed, 164 insertions(+), 27 deletions(-) create mode 100644 .prettierrc delete mode 100644 .vscode/settings.json create mode 100644 webpack-4/README.md diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 0000000..9e26dfe --- /dev/null +++ b/.prettierrc @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index 3ad1c2f..0000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "prettier.singleQuote": false -} diff --git a/README.md b/README.md index b764772..5ae260d 100644 --- a/README.md +++ b/README.md @@ -7,24 +7,33 @@ Jump to the [Webpack 5](./webpack-5/) directory for the most up to date example. ## Running this application ```sh -# switch to the correspoding webpack-4 or webpack-5 directory +# switch to the corresponding webpack-4 or webpack-5 directory npm install -npm run start-4 -npm run start-5 +npm start +# for the built version +npm run build +npm run start:built ``` Navigate to `localhost:8080`. ### Available scripts +The top level scripts in the root directory are mostly for development onf this repo itself: + +- `npm run eslint`, `npm run prettier`, `npm run prettier-check` - Lint this project to maintain code style + +There are also some shortcuts to run the code for each Webpack version. These are just for convenience and behave the same as changing to the sub-directories and running the commands there as shown above. + - `npm run start-4` - Run the Webpack 4 example - `npm run build-4` - Build the Webpack 4 example -- `npm run start-5` - Run the Webpack 4 example -- `npm run build-5` - Build the Webpack 4 example -- `npm run eslint`, `npm run prettier`, `npm run prettier-check` - Lint this project to maintain code style +- `npm run start-5` - Run the Webpack 5 example +- `npm run build-5` - Build the Webpack 5 example ## Requiring Cesium in your application +Regardless which version of Webpack you're using yous should be able to use CesiumJS in the same way. + We recommend [importing named exports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) from the Cesium ES module, via the `import` keyword. This allows webpack to [tree shake](https://webpack.js.org/guides/tree-shaking/) your application automatically. ### Import named modules from Cesium @@ -42,7 +51,20 @@ import "cesium/Build/Cesium/Widgets/widgets.css"; ## Cesium sub-packages -CesiumJS requires a few static files to be hosted on your server, like web workers and SVG icons. This example is set up to copy these directories already if you install the whole `cesium` package. However if you only install `@cesium/engine` then you should change the paths in `webpack.config.js` to the ones below: +CesiumJS requires a few static files to be hosted on your server, like web workers and SVG icons. These examples are set up to copy these directories already if you install the whole `cesium` package. + +```js +new CopyWebpackPlugin({ + patterns: [ + { from: path.join(cesiumSource, "Workers"), to: `${cesiumBaseUrl}/Workers`, }, + { from: path.join(cesiumSource, "ThirdParty"), to: `${cesiumBaseUrl}/ThirdParty`, }, + { from: path.join(cesiumSource, "Assets"), to: `${cesiumBaseUrl}/Assets`, }, + { from: path.join(cesiumSource, "Widgets"), to: `${cesiumBaseUrl}/Widgets`, }, + ], +}), +``` + +However if you only install `@cesium/engine` then you should change the paths in `webpack.config.js` to the ones below: ```js new CopyWebpackPlugin({ @@ -90,8 +112,10 @@ rules: [ Pull requests are appreciated. Please use the same [Contributor License Agreement (CLA)](https://github.com/CesiumGS/cesium/blob/master/CONTRIBUTING.md) used for [Cesium](https://cesium.com/). +Even though this project has nested package.json projects we are not using `npm` workspaces to preserve a more "stand-alone" nature for each example. This allows other developers to copy the sub-directory and use it as-is for a new project. + +Make sure you run `npm install` in the root directory to set up linting and git commit hooks + --- Developed by the Cesium team. - -Even though this project has nested package.json projects we are not using `npm` workspaces to preserve a more "stand-alone" nature for each example. This allows other developers to copy the sub-directory and use it as-is for a new project. diff --git a/webpack-4/README.md b/webpack-4/README.md new file mode 100644 index 0000000..9a8c8fa --- /dev/null +++ b/webpack-4/README.md @@ -0,0 +1,105 @@ +# cesium-webpack-example + +A minimal recommended setup for an applications using [Cesium](https://cesium.com) with [Webpack 4](https://v4.webpack.js.org/concepts/). + +## Running this application + +```sh +npm install +npm start +# for the built version +npm run build +npm run start:built +``` + +Navigate to `localhost:8080`. + +### Available scripts + +- `npm start` - Runs a webpack build with `webpack.config.js` and starts a development server at `localhost:8080` +- `npm run build` - Runs a webpack build with `webpack.config.js` +- `npm run start:built` - Start a small static server using `http-server` to demonstrate hosting the built version + +## Requiring Cesium in your application + +We recommend [importing named exports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) from the Cesium ES module, via the `import` keyword. This allows webpack to [tree shake](https://webpack.js.org/guides/tree-shaking/) your application automatically. + +### Import named modules from Cesium + +```js +import { Color } from "cesium"; +var c = Color.fromRandom(); +``` + +### Import Cesium static asset files + +```js +import "cesium/Build/Cesium/Widgets/widgets.css"; +``` + +## Cesium sub-packages + +CesiumJS requires a few static files to be hosted on your server, like web workers and SVG icons. This example is set up to copy these directories already if you install the whole `cesium` package. + +```js +new CopyWebpackPlugin({ + patterns: [ + { from: path.join(cesiumSource, "Workers"), to: `${cesiumBaseUrl}/Workers`, }, + { from: path.join(cesiumSource, "ThirdParty"), to: `${cesiumBaseUrl}/ThirdParty`, }, + { from: path.join(cesiumSource, "Assets"), to: `${cesiumBaseUrl}/Assets`, }, + { from: path.join(cesiumSource, "Widgets"), to: `${cesiumBaseUrl}/Widgets`, }, + ], +}), +``` + +However if you only install `@cesium/engine` then you should change the paths in `webpack.config.js` to the ones below: + +```js +new CopyWebpackPlugin({ + patterns: [ + { from: 'node_modules/@cesium/engine/Build/Workers', to: `${cesiumBaseUrl}/Workers` }, + { from: 'node_modules/@cesium/engine/Build/ThirdParty', to: `${cesiumBaseUrl}/ThirdParty` }, + { from: 'node_modules/@cesium/engine/Source/Assets', to: `${cesiumBaseUrl}/Assets` }, + ], +}), +``` + +## Removing pragmas + +To remove pragmas such as a traditional Cesium release build, use the [`strip-pragma-loader`](https://www.npmjs.com/package/strip-pragma-loader). + +Install the plugin with npm, + +```sh +npm install strip-pragma-loader --save-dev +``` + +and include the loader in `module.rules` with `debug` set to `false`. + +```js +rules: [ + { + test: /\.js$/, + enforce: "pre", + include: path.resolve(__dirname, cesiumSource), + use: [ + { + loader: "strip-pragma-loader", + options: { + pragmas: { + debug: false, + }, + }, + }, + ], + }, +]; +``` + +## Contributions + +Pull requests are appreciated. Please use the same [Contributor License Agreement (CLA)](https://github.com/CesiumGS/cesium/blob/master/CONTRIBUTING.md) used for [Cesium](https://cesium.com/). + +--- + +Developed by the Cesium team. diff --git a/webpack-4/package.json b/webpack-4/package.json index b16f39c..0421be0 100644 --- a/webpack-4/package.json +++ b/webpack-4/package.json @@ -1,7 +1,7 @@ { "name": "cesiumjs-webpack-4-example", "version": "1.0.0", - "description": "The minimal recommended setup for an app using Cesium with Webpack.", + "description": "The minimal recommended setup for an app using Cesium with Webpack 4", "homepage": "https://cesium.com/platform/cesiumjs/", "license": "Apache-2.0", "author": { diff --git a/webpack-4/webpack.config.js b/webpack-4/webpack.config.js index 11eb833..44e528b 100644 --- a/webpack-4/webpack.config.js +++ b/webpack-4/webpack.config.js @@ -16,10 +16,6 @@ module.exports = { filename: "app.js", path: path.resolve(__dirname, "dist"), }, - // resolve: { - // fallback: { https: false, zlib: false, http: false, url: false }, - // mainFiles: ["index", "Cesium"], - // }, module: { unknownContextCritical: false, rules: [ @@ -39,11 +35,10 @@ module.exports = { plugins: ["@babel/plugin-transform-optional-chaining"], }, }, - // Babel understands import.meta but Webpack doesn't - // can't find a way to tell babel not to output it so we need another loader - // that can understand it and translate into Webpack's representation + // Babel understands the import.meta syntax but doesn't transform it in any way + // However Webpack can't parse this and throws an error for an unexpected token + // we need to use this extra loader so Webpack can actually bundle the code // https://www.npmjs.com/package/@open-wc/webpack-import-meta-loader - // TODO: but then we get static dependency errors about `require` in buildModuleUrl instead require.resolve("@open-wc/webpack-import-meta-loader"), ], }, diff --git a/webpack-5/README.md b/webpack-5/README.md index abc2e05..d880e62 100644 --- a/webpack-5/README.md +++ b/webpack-5/README.md @@ -1,22 +1,24 @@ # cesium-webpack-example -A minimal recommended setup for an applications using [Cesium](https://cesium.com) with [Webpack](https://webpack.js.org/concepts/). - -[![Build Status](https://travis-ci.org/CesiumGS/cesium-webpack-example.svg?branch=using-custom-loader)](https://travis-ci.org/CesiumGS/cesium-webpack-example) +A minimal recommended setup for an applications using [Cesium](https://cesium.com) with [Webpack 5](https://webpack.js.org/concepts/). ## Running this application ```sh npm install npm start +# for the built version +npm run build +npm run start:built ``` Navigate to `localhost:8080`. ### Available scripts -- `npm start` - Runs a webpack build with `webpack.config.js` and starts a development server +- `npm start` - Runs a webpack build with `webpack.config.js` and starts a development server at `localhost:8080` - `npm run build` - Runs a webpack build with `webpack.config.js` +- `npm run start:built` - Start a small static server using `http-server` to demonstrate hosting the built version ## Requiring Cesium in your application @@ -37,7 +39,20 @@ import "cesium/Build/Cesium/Widgets/widgets.css"; ## Cesium sub-packages -CesiumJS requires a few static files to be hosted on your server, like web workers and SVG icons. This example is set up to copy these directories already if you install the whole `cesium` package. However if you only install `@cesium/engine` then you should change the paths in `webpack.config.js` to the ones below: +CesiumJS requires a few static files to be hosted on your server, like web workers and SVG icons. This example is set up to copy these directories already if you install the whole `cesium` package. + +```js +new CopyWebpackPlugin({ + patterns: [ + { from: path.join(cesiumSource, "Workers"), to: `${cesiumBaseUrl}/Workers`, }, + { from: path.join(cesiumSource, "ThirdParty"), to: `${cesiumBaseUrl}/ThirdParty`, }, + { from: path.join(cesiumSource, "Assets"), to: `${cesiumBaseUrl}/Assets`, }, + { from: path.join(cesiumSource, "Widgets"), to: `${cesiumBaseUrl}/Widgets`, }, + ], +}), +``` + +However if you only install `@cesium/engine` then you should change the paths in `webpack.config.js` to the ones below: ```js new CopyWebpackPlugin({ diff --git a/webpack-5/package.json b/webpack-5/package.json index 7efbf14..9dc3944 100644 --- a/webpack-5/package.json +++ b/webpack-5/package.json @@ -1,7 +1,7 @@ { "name": "cesiumjs-webpack-5-example", "version": "1.0.0", - "description": "The minimal recommended setup for an app using Cesium with Webpack.", + "description": "The minimal recommended setup for an app using Cesium with Webpack 5", "homepage": "https://cesium.com/platform/cesiumjs/", "license": "Apache-2.0", "author": { From d21e8d31cd2f2e91c527ecdad265a757c51cd8c9 Mon Sep 17 00:00:00 2001 From: Josh <8007967+jjspace@users.noreply.github.com> Date: Thu, 11 Jan 2024 14:16:53 -0500 Subject: [PATCH 10/10] reorganize docs --- README.md | 42 ++++++++++++++++++------------------------ 1 file changed, 18 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 5ae260d..8165104 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,19 @@ # cesium-webpack-example -A minimal recommended setup for an applications using [Cesium](https://cesium.com) with [Webpack](https://webpack.js.org/concepts/). +A minimal recommended setup for an applications using [Cesium](https://cesium.com) with [Webpack](https://webpack.js.org/). Jump to the [Webpack 5](./webpack-5/) directory for the most up to date example. We also provide a [Webpack 4](./webpack-4/) example if you are still on the older version. ## Running this application -```sh -# switch to the corresponding webpack-4 or webpack-5 directory -npm install -npm start -# for the built version -npm run build -npm run start:built -``` - -Navigate to `localhost:8080`. - -### Available scripts - -The top level scripts in the root directory are mostly for development onf this repo itself: +Please switch to the corresponding sub-directory for the version of Webpack you're using to see how to run this example application -- `npm run eslint`, `npm run prettier`, `npm run prettier-check` - Lint this project to maintain code style - -There are also some shortcuts to run the code for each Webpack version. These are just for convenience and behave the same as changing to the sub-directories and running the commands there as shown above. - -- `npm run start-4` - Run the Webpack 4 example -- `npm run build-4` - Build the Webpack 4 example -- `npm run start-5` - Run the Webpack 5 example -- `npm run build-5` - Build the Webpack 5 example +- [Webpack 4 commands](./webpack-4/README.md#running-this-application) +- [Webpack 5 commands](./webpack-5/README.md#running-this-application) ## Requiring Cesium in your application -Regardless which version of Webpack you're using yous should be able to use CesiumJS in the same way. +Regardless which version of Webpack you're using you should be able to use CesiumJS in the same way. We recommend [importing named exports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) from the Cesium ES module, via the `import` keyword. This allows webpack to [tree shake](https://webpack.js.org/guides/tree-shaking/) your application automatically. @@ -116,6 +97,19 @@ Even though this project has nested package.json projects we are not using `npm` Make sure you run `npm install` in the root directory to set up linting and git commit hooks +### Available scripts + +The top level scripts in the root directory are mostly for development of this repo itself: + +- `npm run eslint`, `npm run prettier`, `npm run prettier-check` - Lint this project to maintain code style + +There are also some shortcuts to run the code for each Webpack version. These are just for convenience and behave the same as changing to the sub-directories and running the commands there + +- `npm run start-4` - Run the Webpack 4 example +- `npm run build-4` - Build the Webpack 4 example +- `npm run start-5` - Run the Webpack 5 example +- `npm run build-5` - Build the Webpack 5 example + --- Developed by the Cesium team.