{"id":22644,"library":"vite-plugin-elm-watch","title":"vite-plugin-elm-watch","description":"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.","status":"active","version":"1.4.4","language":"javascript","source_language":"en","source_url":"https://github.com/ryannhg/vite-plugin-elm-watch","tags":["javascript","elm","vite","plugin","elm-watch","typescript"],"install":[{"cmd":"npm install vite-plugin-elm-watch","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-elm-watch","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-elm-watch","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency providing reliable HMR for Elm modules","package":"elm-watch","optional":false},{"reason":"Enables clicking on error messages to open the editor at the error location","package":"launch-editor","optional":false}],"imports":[{"note":"ESM-only; CommonJS require() will fail because the package is ESM.","wrong":"const elm = require('vite-plugin-elm-watch')","symbol":"default","correct":"import elm from 'vite-plugin-elm-watch'"},{"note":"TypeScript type export for options object; only available if using TypeScript.","wrong":"","symbol":"ElmPluginOptions","correct":"import type { ElmPluginOptions } from 'vite-plugin-elm-watch'"},{"note":"Useful when typing the return value of importing an .elm file.","wrong":"","symbol":"ElmModule (return type)","correct":"import type { ElmModule } from 'vite-plugin-elm-watch'"}],"quickstart":{"code":"// vite.config.js\nimport { defineConfig } from 'vite'\nimport elm from 'vite-plugin-elm-watch'\n\nexport default defineConfig({\n  plugins: [elm({ mode: 'auto', output: 'default' })]\n})\n\n// src/main.js\n// Elm file (Main.elm) exposing 'main' using Browser.element\nimport Main from './src/Main.elm'\n\nlet app = Main.init({\n  node: document.getElementById('root'),\n  flags: { user: 'Alice' }\n})\n\n// For React output mode:\n// src/App.tsx\n// import ElmComponent from './src/Hello.elm'\n// function App() { return <ElmComponent name=\"World\" /> }","lang":"javascript","description":"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."},"warnings":[{"fix":"Wrap Elm components in a container that handles unmounting lifecycle carefully, or avoid swapping Elm/React components at runtime.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Do not rely on id attributes on the root node after Elm initialization; use class names or data attributes instead.","message":"Enabling isBodyPatchEnabled will clear the id attribute from the root element after Elm loads, as Elm removes attributes from its root node.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure Vite's root configuration points to the correct project root. Previously relied on process.cwd() which could be inconsistent.","message":"In 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.","severity":"breaking","affected_versions":">=1.4.2"},{"fix":"Upgrade to v1.4.0 or later for proper Browser.application support.","message":"Version 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.","severity":"gotcha","affected_versions":"<1.4.0"},{"fix":"Update to v1.3.5 or later to fix Windows HMR path detection.","message":"Windows HMR detection could fail in v1.3.5 and earlier due to differences in path separators (/ vs \\).","severity":"gotcha","affected_versions":"<1.3.5"},{"fix":"Test your specific use case thoroughly, especially HMR and React interop.","message":"The plugin is still experimental and may have undiscovered bugs; not recommended for production without thorough testing.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"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.","cause":"The package is ESM-only (exports ES modules) but you are using require() or have CommonJS project settings.","error":"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."},{"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.","cause":"Attempting to unmount an Elm app that was not properly initialized or React component unmount ordering issue.","error":"TypeError: Cannot read properties of undefined (reading 'app') / Uncaught TypeError: app.unmount is not a function"},{"fix":"Use a single version of Elm and ensure your bundler (Vite) handles Elm modules correctly. Avoid mixing CDN and bundled Elm.","cause":"Multiple copies of Elm runtime or incorrect module resolution when using UMD builds.","error":"Error: Mismatched anonymous define() module: function..."},{"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.","cause":"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.","error":"Uncaught (in promise) TypeError: elm.init is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}