DocsMigration Guide

Migration Guide

Migrate your existing project to Lunx in minutes. Covers Vite and Webpack migrations with step-by-step instructions, config mappings, and a compatibility reference.

Updated for Lunx v1.0.2

Migrating from Vite

Since Lunx uses a compatible ESM-first architecture, migrating from Vite typically takes under 10 minutes. Most Vite plugins have direct Lunx equivalents — or work without modification.

1. Update dependencies

bash

# Remove Vite and framework plugins
npm uninstall vite @vitejs/plugin-react @vitejs/plugin-vue

# Install Lunx
npm install --save-dev lunx-dev

2. Replace vite.config.ts

Before — vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: { port: 3000 },
  build: {
    outDir: 'dist',
    minify: 'esbuild',
  },
})

After — lunx.config.ts

import { defineConfig } from 'lunx'

export default defineConfig({
  framework: 'react',    // adapter replaces plugin
  server: { port: 3000 },
  build: {
    outDir: 'dist',
    minify: true,        // SWC + LightningCSS
  },
})

3. Update package.json scripts

jsonpackage.json

{
  "scripts": {
-   "dev":     "vite",
-   "build":   "tsc && vite build",
-   "preview": "vite preview"
+   "dev":     "lunx dev",
+   "build":   "lunx build",
+   "preview": "lunx preview"
  }
}

4. Vite → Lunx API mapping

Vite concept	Lunx equivalent
@vitejs/plugin-react	framework: 'react' (built-in adapter)
@vitejs/plugin-vue	framework: 'vue' (built-in adapter)
vite-plugin-svgr	@lunx/plugin-svg
vite-pwa	@lunx/plugin-pwa
vite-plugin-compression	@lunx/plugin-compress
@vitejs/plugin-legacy	@lunx/plugin-legacy
vite-plugin-checker	@lunx/plugin-checker
vite-plugin-inspect	@lunx/plugin-inspect (at /__lunx_inspect__)
import.meta.env.VITE_*	import.meta.env.LUNX_PUBLIC_* (rename vars)

Rename VITE_ prefix to LUNX_PUBLIC_

Lunx uses LUNX_PUBLIC_ instead of VITE_ for browser-safe env vars. Rename all VITE_* variables in your .env files and update all import.meta.env.VITE_* accesses in source code before building.

Migrating from Webpack

Moving from Webpack eliminates complex loaders (babel-loader, ts-loader, css-loader, sass-loader) and custom plugin configurations. Lunx handles all transforms natively in Rust.

1. Remove Webpack dependencies

bash

npm uninstall webpack webpack-cli webpack-dev-server   babel-loader ts-loader css-loader style-loader   sass-loader html-webpack-plugin mini-css-extract-plugin   terser-webpack-plugin

npm install --save-dev lunx-dev

2. Replace webpack.config.js

typescriptlunx.config.ts

import { defineConfig } from 'lunx'

export default defineConfig({
  // framework auto-detected from package.json
  framework: 'react',

  // Webpack entry → Lunx entry (auto-detected from src/main.tsx)
  // entry: 'src/main.tsx',

  // Webpack output.path → Lunx outDir
  build: { outDir: 'dist' },

  // Webpack devServer → Lunx server
  server: {
    port: 3000,
    proxy: { '/api': 'http://localhost:8080' },
  },

  // Webpack resolve.alias → Lunx resolve.alias
  resolve: {
    alias: { '@': './src' },  // @/ is auto-aliased by default
  },
})

3. Update your HTML entry

Webpack injects bundles into HTML templates via HtmlWebpackPlugin. Lunx uses a standard index.html with a direct script tag pointing to your entry point.

htmlindex.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My Lunx App</title>
  </head>
  <body>
    <div id="root"></div>
    <!-- Direct ESM entry point — Lunx resolves and bundles this -->
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

4. Webpack concept mapping

Webpack	Lunx equivalent
babel-loader + ts-loader	SWC (built-in, no config needed)
css-loader + style-loader	LightningCSS (built-in)
sass-loader	LightningCSS (supports @import natively)
mini-css-extract-plugin	Built-in CSS code splitting
HtmlWebpackPlugin	index.html with direct script tag
terser-webpack-plugin	SWC minifier (build.minify: true)
DefinePlugin	config.define: {}
resolve.alias	resolve.alias: {} or @/ auto-alias
optimization.splitChunks	build.rollupOptions.output.manualChunks
webpack-bundle-analyzer	lunx build --analyze

No more loaders

Lunx's Rust compiler handles TypeScript, JSX, CSS (including nesting, custom properties, and modern features), and asset transforms natively. You'll delete thousands of lines of Webpack configuration and still get faster builds.

PreviousSBOM Guide NextChangelog