Registry / web-framework / vite-plugin-elm-watch

vite-plugin-elm-watch

library1.4.4jsnpmunverified

A Vite plugin for seamlessly integrating Elm into your Vite project with reliable Hot Module Replacement (HMR) powered by elm-watch, full-color error overlays, and JS minification for production builds. Current stable version is 1.4.4. The plugin supports multiple Elm compiler modes (debug, optimize, minify) and can export Elm apps as standard objects or React components. It automatically patches DOM for Browser.application usage and provides clickable error links to launch your editor. Experimental but actively maintained.

web-framework

npm install vite-plugin-elm-watch

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-ELM-WA

vite-plugin-elm-watch

web-frameworkjavascriptv1.4.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import elm from 'vite-plugin-elm-watch'

✗ const elm = require('vite-plugin-elm-watch')

ESM-only; CommonJS require() will fail because the package is ESM.

ElmPluginOptions

✓ import type { ElmPluginOptions } from 'vite-plugin-elm-watch'

TypeScript type export for options object; only available if using TypeScript.

ElmModule (return type)

✓ import type { ElmModule } from 'vite-plugin-elm-watch'

Useful when typing the return value of importing an .elm file.

Basic setup for a Vite project with Elm: install plugin, configure in vite.config.js, and import .elm files. Shows both default and React output modes.

// vite.config.js import { defineConfig } from 'vite' import elm from 'vite-plugin-elm-watch' export default defineConfig({ plugins: [elm({ mode: 'auto', output: 'default' })] }) // src/main.js // Elm file (Main.elm) exposing 'main' using Browser.element import Main from './src/Main.elm' let app = Main.init({ node: document.getElementById('root'), flags: { user: 'Alice' } }) // For React output mode: // src/App.tsx // import ElmComponent from './src/Hello.elm' // function App() { return <ElmComponent name="World" /> }

Debug

Known issues

gotchaWhen using 'react' output mode, swapping an Elm component with a .tsx component can cause unmount errors because React removes the DOM node before Elm's app.unmount() runs.

fix

Wrap Elm components in a container that handles unmounting lifecycle carefully, or avoid swapping Elm/React components at runtime.

affects: >=1.0.0

gotchaEnabling isBodyPatchEnabled will clear the id attribute from the root element after Elm loads, as Elm removes attributes from its root node.

fix

Do not rely on id attributes on the root node after Elm initialization; use class names or data attributes instead.

affects: >=1.0.0

breakingIn version 1.4.2, the plugin changed from using process.cwd() to viteConfig.root for running elm make, which may affect projects where Vite's root is different from the working directory.

fix

Ensure Vite's root configuration points to the correct project root. Previously relied on process.cwd() which could be inconsistent.

affects: >=1.4.2

gotchaVersion 1.4.0 fixed a bug with patching DOM nodes internally; projects using Browser.application may have encountered issues with body patching before this fix.

fix

Upgrade to v1.4.0 or later for proper Browser.application support.

affects: <1.4.0

gotchaWindows HMR detection could fail in v1.3.5 and earlier due to differences in path separators (/ vs \).

fix

Update to v1.3.5 or later to fix Windows HMR path detection.

affects: <1.3.5

gotchaThe plugin is still experimental and may have undiscovered bugs; not recommended for production without thorough testing.

fix

Test your specific use case thoroughly, especially HMR and React interop.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/vite-plugin-elm-watch/dist/index.js from /path/to/vite.config.js not supported.

The package is ESM-only (exports ES modules) but you are using require() or have CommonJS project settings.

fix

Change your vite.config.js to use import syntax: import elm from 'vite-plugin-elm-watch'. Also ensure your package.json has "type": "module" or rename file to .mjs.

TypeError: Cannot read properties of undefined (reading 'app') / Uncaught TypeError: app.unmount is not a function

Attempting to unmount an Elm app that was not properly initialized or React component unmount ordering issue.

fix

If using React output, ensure the component is never swapped with a non-Elm component without proper cleanup. For standard mode, call init() before unmount.

Error: Mismatched anonymous define() module: function...

Multiple copies of Elm runtime or incorrect module resolution when using UMD builds.

fix

Use a single version of Elm and ensure your bundler (Vite) handles Elm modules correctly. Avoid mixing CDN and bundled Elm.

Uncaught (in promise) TypeError: elm.init is not a function

The imported Elm module does not have an init method; likely the .elm file does not expose 'main' correctly or the plugin version is incompatible.

fix

Ensure your Elm file defines a 'main' value using Browser.element, Browser.document, or Browser.application. Also verify that the plugin output mode matches your usage.

Upgrade

Version history

1.4.4latest on npm

Audit

Dependencies

elm-watchrequiredCore dependency providing reliable HMR for Elm modules

launch-editorrequiredEnables clicking on error messages to open the editor at the error location

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ryannhg/vite-plugin-elm-watch ↗

packagehttps://www.npmjs.com/package/vite-plugin-elm-watch ↗