@shadow-js/vite

v0.3.0

Published

6 months ago

Vite plugin for ShadowJS (JSX + transforms via SWC)

0High
0Medium
0Low

jehaad

shadowjs vite plugin jsx swc

ShadowJS Vite Plugin

Vite plugin for ShadowJS that provides seamless development experience with hot reload, JSX compilation, and optimized build process.

✨ Features

⚡ Hot Module Replacement: Instant updates during development
🎯 JSX Compilation: Automatic ShadowJS JSX transformations
🔧 Zero Configuration: Works out of the box with sensible defaults
🎨 TypeScript Support: Full TypeScript and TSX compilation
📦 Optimized Builds: Production-ready bundle optimization
🔍 Source Maps: Accurate debugging with source map support
🎭 Development Server: Fast development server with HMR
📱 Modern Standards: ES2022+ with modern browser support

📦 Installation

npm install @shadow-js/vite

Install together with ShadowJS:

npm install @shadow-js/core @shadow-js/vite

🚀 Quick Start

Basic Setup

vite.config.ts

import { defineConfig } from "vite";
import shadow from "@shadow-js/vite";

export default defineConfig({
  plugins: [shadow()],
});

src/App.tsx

import { useStore, Show } from "@shadow-js/core";

function App() {
  const [count, setCount] = useStore(0);

  return (
    <div>
      <h1>ShadowJS Counter</h1>
      <button onClick={() => setCount((c) => c + 1)}>Count: {count()}</button>
      <Show when={count() > 5}>
        <p>🎉 You reached {count()}!</p>
      </Show>
    </div>
  );
}

export default App;

src/main.ts

import { render } from "@shadow-js/core";
import App from "./App";

render(App, document.getElementById("app")!);

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>ShadowJS App</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

Development Commands

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

🎯 How It Works

The plugin integrates ShadowJS with Vite's build pipeline:

1. Development Mode

Hot Module Replacement: Instant updates without page refresh
Source Maps: Accurate debugging information
Error Overlay: Clear error messages in browser

2. Build Process

JSX Compilation: Transforms TSX/JSX using ShadowJS compiler
TypeScript Compilation: Converts TypeScript to JavaScript
JSX Runtime Injection: Automatically imports ShadowJS runtime
Code Splitting: Optimizes bundle size with code splitting
Minification: Production-ready code minification

3. Plugin Architecture

Source Code (.tsx)
    ↓
ShadowJS Compiler (JSX → Reactive)
    ↓
SWC (TypeScript → JavaScript)
    ↓
Vite (Bundling & Optimization)
    ↓
Output Bundle

🔧 Configuration

Basic Configuration

// vite.config.ts
import { defineConfig } from "vite";
import shadow from "@shadow-js/vite";

export default defineConfig({
  plugins: [shadow()],
  // Your other Vite configuration
});

Advanced Configuration

// vite.config.ts
import { defineConfig } from "vite";
import shadow from "@shadow-js/vite";

export default defineConfig({
  plugins: [
    shadow({
      // Plugin-specific options (future)
    }),
  ],

  // Vite configuration
  server: {
    port: 3000,
    open: true,
  },

  build: {
    target: "es2022",
    minify: "esbuild",
  },

  // TypeScript configuration
  esbuild: {
    // Vite handles TypeScript compilation
  },
});

With Other Vite Plugins

The ShadowJS plugin works well with other Vite plugins:

import { defineConfig } from "vite";
import shadow from "@shadow-js/vite";
import { viteStaticCopy } from "vite-plugin-static-copy";

export default defineConfig({
  plugins: [
    shadow(),
    viteStaticCopy({
      targets: [
        {
          src: "static/*",
          dest: "assets",
        },
      ],
    }),
  ],
});

🏗️ Plugin Architecture

Core Components

| Component | Description | | ---------------------- | --------------------------------------------- | | JSX Transform | Converts ShadowJS JSX to reactive expressions | | TypeScript Support | Handles TypeScript compilation via SWC | | HMR Integration | Manages hot module replacement | | Source Maps | Generates source maps for debugging | | Error Handling | Provides clear error messages |

Transformation Pipeline

File Detection: Identifies .tsx and .jsx files
ShadowJS Compilation: Applies JSX transformations
SWC Processing: Handles TypeScript/JSX to JavaScript conversion
Runtime Injection: Adds necessary ShadowJS imports
Source Map Generation: Creates debugging source maps

Development Features

Fast Refresh: Instant updates during development
Error Boundaries: Development-friendly error handling
Console Integration: Clear logging and debugging messages
Type Checking: Real-time TypeScript error reporting

🎨 Development Experience

Hot Module Replacement

The plugin provides seamless HMR for ShadowJS components:

// This component will hot-reload automatically
function Counter() {
  const [count, setCount] = useStore(0);

  return <button onClick={() => setCount((c) => c + 1)}>{count()}</button>;
}

TypeScript Integration

Full TypeScript support with IntelliSense:

// TypeScript types work perfectly
function UserComponent({ user }: { user: User }) {
  const [isEditing, setIsEditing] = useStore(false);

  return (
    <div>
      <h2>{user().name}</h2>
      <button onClick={() => setIsEditing((v) => !v)}>
        {isEditing() ? "Cancel" : "Edit"}
      </button>
    </div>
  );
}

🤝 Contributing

We welcome any contributions! See the Contributing Guide for details.

Areas for contribution:

Performance optimizations
New plugin features
Better error messages
Enhanced TypeScript support
Additional build optimizations

📄 License

MIT License - see LICENSE for details.

📞 Support

Documentation: Vite Plugin Guide
Examples: Integration Examples
Issues: GitHub Issues
Discussions: GitHub Discussions

Built by Jehaad AL-Johani for the ShadowJS ecosystem.