Migrate to Vite 8 by tordans · Pull Request #12411 · openstreetmap/iD

tordans · 2026-06-06T19:47:28Z

As discussed no Slack, this is a take on migrating to Vite 8.

I tested the app a bit an all looks nice. Changing light<>dark mode on a system level still works.

Replace esbuild + standalone CSS concat with Vite (vite.config.ts, main.ts entry)
- Dev: npm start runs build:data then Vite HMR (no separate JS watch/server)
- Prod: dist/iD.js / dist/iD.min.js / dist/iD.css with stable names for embedders
Move env config from esbuild define to import.meta.env (config/env.ts, config/id.ts)
Keep PostCSS plugin for .ideditor scoping + dark-mode duplication; Lightning CSS for autoprefix
Hand-maintain dist/index.html (minimal diff: inline loader → <script type="module">)
Merge Vitest into vite.config.ts; broaden tsconfig to **/*.ts
PR preview deploys from dist/; add netlify.toml
Bump Vite ecosystem deps to latest (vite, vitest, postcss, browserslist, rollup-plugin-visualizer)
Suppress Vite warning for test data imports
Simplify build and dev scripts

Possible follow ups

Migrate to a more classic public directory asset strategy. This will make things like https://github.com/openstreetmap/iD/pull/12411/changes#r3368185484 a lot easier
Simplify the css rewrites, see https://github.com/openstreetmap/iD/pull/12411/changes#r3368169678
Replace the scripts dist:mapillary, dist:pannellum with native Vite lazy loading.

Migrate build from esbuild to Vite 8 - Replace esbuild + standalone CSS concat with Vite (`vite.config.ts`, `main.ts` entry) - Dev: `npm start` runs `build:data` then Vite HMR (no separate JS watch/server) - Prod: `dist/iD.js` / `dist/iD.min.js` / `dist/iD.css` with stable names for embedders - Move env config from esbuild `define` to `import.meta.env` (`config/env.ts`, `config/id.ts`) - Keep PostCSS plugin for `.ideditor` scoping + dark-mode duplication; Lightning CSS for autoprefix - Hand-maintain `dist/index.html` (minimal diff: inline loader → `<script type="module">`) - Merge Vitest into `vite.config.ts`; broaden `tsconfig` to `**/*.ts` - PR preview deploys from `dist/`; add `netlify.toml` - Bump Vite ecosystem deps to latest (vite, vitest, postcss, browserslist, rollup-plugin-visualizer) - Suppress Vite warning for test data imports - Simplify build and dev scripts

tordans · 2026-06-06T20:08:15Z

+ * Client env values from import.meta.env (Vite envPrefix: 'ID_').
+ * Used by config/id.ts for CDN URLs, API connection, and feature flags.
+ */
+export const idPresetsCdnUrl: string | null = import.meta.env.ID_PRESETS_CDN_URL ?? null;


Note: We override the Vite default envPrefix for public env.* to ID_* which is why this works.

tordans · 2026-06-06T20:08:58Z

Same idea, now in config/env.ts. We could preserve the names ENV_* but given that config/id.ts reassigns many of them anyways, this looks nicer to me.

tordans · 2026-06-06T20:09:55Z

Nearly each line was touched, so I migrated this to TS as a byproduct.

tordans · 2026-06-06T20:11:28Z

Vite and lightning handles the CSS now.

tordans · 2026-06-06T20:11:55Z

+/**
+ * Single CSS entry for Vite. Order matches previous build_css.js (sorted by filename).
+ */


Suggested change

/**

* Single CSS entry for Vite. Order matches previous build_css.js (sorted by filename).

*/

We don't need this.

tordans · 2026-06-06T20:14:56Z

This is one of the more interesting changes…
Here is some explanation summary from Cursor:

With Vite, scripts/build_css.ts is not a separate build step anymore — it is a Vite plugin (idCssPlugin) that applies two transforms iD still depends on, which Vite/Lightning CSS do not provide on their own.

What it does

When Vite processes any file in the css/ tree (via css/entry.css → @import chain in main.ts), the plugin runs PostCSS with two plugins:

1. Scope all styles under .ideditor

Most source CSS is written with bare selectors:

path.line.shadow.tag-aerialway, path.line.shadow.tag-attraction-summer_toboggan, ...

At runtime, iD mounts into a container with class ideditor (set in context.js). The plugin uses postcss-prefix-selector to turn .foo into .ideditor .foo so styles do not leak onto the host page when iD is embedded. Selectors that already start with .ideditor are skipped via the exclude regex.

2. Make OS dark mode work with explicit theme choice

Authors write dark styles the natural way:

@media (prefers-color-scheme: dark) { .ideditor {

iD also lets users pick light, dark, or system in settings (theme-light / theme-dark classes on the container). The custom duplicate-from-media plugin rewrites those @media (prefers-color-scheme: dark) blocks:

Original rules get :not(.theme-light) — explicit light theme ignores OS dark preference

Duplicated rules get .theme-dark — explicit dark theme applies dark styles even on a light OS

Without this, “use dark theme” in iD settings would not work reliably when the OS preference disagrees.

Why it exists as its own file

Concern Handled by

Bundle JS, HMR, output iD.css Vite

Autoprefixer / browser targets Lightning CSS (css.transformer: 'lightningcss')

.ideditor prefix + theme duplication scripts/build_css.ts

The pre-Vite setup had a standalone scripts/build_css.js that did the same PostCSS work. After the Vite migration, that logic became a plugin so it runs in dev and production on the same CSS pipeline — no duplicate “build CSS then build JS” step.

What it deliberately does not do

The file header says it only handles prefix + dark-mode. Autoprefixer was removed from PostCSS here because Lightning CSS already covers that via browserslist in vite.config.ts.

In short: iD’s CSS is authored as if it were page-global (short selectors + @media (prefers-color-scheme: dark)). build_css.ts adapts that legacy style to iD’s embedding model and theme API. Until someone rewrites all css/*.css with explicit .ideditor prefixes and .theme-dark rules by hand, this plugin is required.

A follow-up from the migration plan was to eventually drop the PostCSS dark-mode duplication once CSS is simplified — that would be a large CSS refactor, not a Vite config tweak.

tordans · 2026-06-06T20:17:19Z

-    "build": "run-s build:css build:data build:js",
-    "build:css": "node scripts/build_css.js",
+    "build": "run-s build:data build:app",
+    "build:app": "vite build",
    "build:data": "shx mkdir -p dist/data && node scripts/build_data.js",
-    "build:stats": "node config/esbuild.config.min.js --stats && esbuild-visualizer --metadata dist/esbuild.json --filename docs/statistics.html && shx rm dist/esbuild.json",
-    "build:js": "node config/esbuild.config.js",
-    "build:js:watch": "node config/esbuild.config.js --watch",


This is simplified. Vite handles the minification (and source map) and JS build.

tordans · 2026-06-06T20:18:01Z

-    "start": "run-s start:watch",
-    "start:single-build": "run-p build:js start:server",
-    "start:watch": "run-p build:js:watch start:server",
-    "start:server": "node scripts/server.js",
-    "test": "npm-run-all -s lint build test:typecheck test:spec",
+    "start": "npm run build:data && vite",
+    "test": "run-s lint build test:typecheck test:spec",


This is simplified as well. Vite does a lot of the reload and watch internally.

tordans · 2026-06-06T20:18:24Z

        "types": ["vitest/globals", "vitest/jsdom"]
    },
-    "include": ["modules", "test"]
+    "include": ["**/*.ts"]


We can simplify this.

we need to include JS files too (since definitions can be imported between both files).

could we just keep this line as-is ?

tordans · 2026-06-06T20:18:51Z

+
+export default defineConfig(() => ({
+  base: './',
+  envPrefix: 'ID_',


See config/env.ts.

tordans · 2026-06-06T20:19:30Z

Now inline in vite.config.ts as test prop.

k-yle

this is just a very quick review, following the meeting today. i haven't tried it out yet

k-yle · 2026-06-10T10:56:44Z

+
+declare global {
+  interface Window {
+    context?: iD.Context;


if this is whitelisted as a global, i would mark this as @deprecated or something, so that we don't accidentally use it.

Suggested change

context?: iD.Context;

/** @deprecated */

context?: iD.Context;

or alternatively, mark this as a banned global variable in eslint.config.js (see #12210)

k-yle · 2026-06-10T11:16:40Z

@@ -0,0 +1 @@
+declare module 'postcss-prefix-selector';


it would be better to import @types/postcss-prefix-selector rather than silencing the warning

k-yle · 2026-06-10T11:17:58Z

+ * Entry point for the iD editor (Vite dev and build).
+ * In dev, Vite serves this and transforms on the fly; in build, this is bundled to dist/iD.min.js.
+ */
+import './css/entry.css';


I'm guessing this import magic will be converted into a <link rel="stylesheet" /> tag?

If so, then so then this only applies to the standalone build? because the OSM website will load iD.css and iD.js directly, right?

k-yle · 2026-06-10T11:19:35Z

@@ -0,0 +1,15 @@
+/**
+ * Client env values from import.meta.env (Vite envPrefix: 'ID_').
+ * Used by config/id.ts for CDN URLs, API connection, and feature flags.


can we just delete this file? with a modern bundler we don't need a file that reëxports everything.

and import.meta.env.* is type-safe already

k-yle · 2026-06-10T11:20:17Z

-    "build:js": "node config/esbuild.config.js",
-    "build:js:watch": "node config/esbuild.config.js --watch",
-    "clean": "shx rm -f dist/esbuild.json dist/*.js dist/*.map dist/*.css dist/img/*.svg",
+    "build:stats": "BUILD_STATS=true vite build",


this won't work on windows, can we use cross-env (or whatever the modern replacement is - shx and shelljs are both already installed)

or can we use a CLI argument instead?

k-yle · 2026-06-10T11:20:34Z

        "types": ["vitest/globals", "vitest/jsdom"]
    },
-    "include": ["modules", "test"]
+    "include": ["**/*.ts"]


we need to include JS files too (since definitions can be imported between both files).

could we just keep this line as-is ?

k-yle · 2026-06-10T11:20:48Z

+  css: {
+    transformer: 'lightningcss',
+    lightningcss: {
+      targets: browserslistToTargets(browserslist()),


the only place where browserlist is used is here, for CSS.

do we need to link the browserslist to the JS somehow? vite uses build.target instead.

or - should we delete the browserlist config and rewrite it using vite's syntax? that might be easier

k-yle · 2026-06-10T11:34:12Z

-          container.style.padding = '20px';
-
-        } else {
-          var context = iD.coreContext()


all this code is copy-pasted (with modifications) in the osm-website repo.

so any changes needs to be coordinated with them.

we could solve #11039 at the same time by exposing context differently - I've commented at #11039 (comment)

k-yle · 2026-06-10T11:34:43Z

+  if (!context) return;
+
+  window.context = context;
+  window.id = context;


previously, this was only available in debug mode. now it's available in production, so people might start using it.

I think we need to find a conclusion to #11039 first, before people start relying on this hack

tordans requested a review from Copilot June 6, 2026 19:48

Copilot started reviewing on behalf of tordans June 6, 2026 19:48 View session

github-actions Bot deployed to pr-preview-12411 June 6, 2026 19:50 View deployment

This comment was marked as low quality.

Sign in to view

tordans force-pushed the vite8b branch from 3010313 to db43831 Compare June 6, 2026 20:04

tordans force-pushed the vite8b branch from db43831 to 02b5d77 Compare June 6, 2026 20:06

github-actions Bot deployed to pr-preview-12411 June 6, 2026 20:07 View deployment

tordans commented Jun 6, 2026

View reviewed changes

github-actions Bot deployed to pr-preview-12411 June 6, 2026 20:09 View deployment

tordans commented Jun 6, 2026

View reviewed changes

tordans requested a review from k-yle June 6, 2026 20:41

tyrasd added the chore-build Improvements to the iD build scripts / CI environment label Jun 9, 2026

k-yle mentioned this pull request Jun 10, 2026

Support Extension Access to coreContext in Production #11039

Open

k-yle reviewed Jun 10, 2026

View reviewed changes

	/**
	* Single CSS entry for Vite. Order matches previous build_css.js (sorted by filename).
	*/

Concern	Handled by
Bundle JS, HMR, output `iD.css`	Vite
Autoprefixer / browser targets	Lightning CSS (`css.transformer: 'lightningcss'`)
`.ideditor` prefix + theme duplication	`scripts/build_css.ts`

	context?: iD.Context;
	/** @deprecated */
	context?: iD.Context;

Conversation

tordans commented Jun 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Possible follow ups

Uh oh!

This comment was marked as low quality.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

What it does

1. Scope all styles under .ideditor

2. Make OS dark mode work with explicit theme choice

Why it exists as its own file

What it deliberately does not do

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

k-yle Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

k-yle left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

k-yle Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

tordans commented Jun 6, 2026 •

edited

Loading

1. Scope all styles under `.ideditor`

k-yle Jun 10, 2026 •

edited

Loading

k-yle Jun 10, 2026 •

edited

Loading