⚡ Sparx — Modern Build Tool

Sparx is a production-grade JavaScript/TypeScript build tool powered by SWC (Rust) and LightningCSS. It delivers sub-100ms HMR, native Module Federation for micro-frontends, full ES2022+ support, automatic tree shaking, a security gate pipeline, and zero-config support for 19 meta-frameworks — a modern alternative to Webpack/Vite with a Rust-native core.

✨ Features

🚀 Quick Start

# Install globally
npm install -g sparx

# Create a new project (interactive)
sparx create my-app --framework react --ts

# Or scaffold with a template
sparx bootstrap --name my-app --template react-ts

# Start dev server
cd my-app
sparx dev

# Production build
sparx build

📦 Installation

npm install -g sparx
# or per-project
npm install -D sparx

Requirements: Node.js ≥ 20

⚙️ Configuration — sparx.config.ts

// sparx.config.ts
import { defineConfig } from 'sparx';

export default defineConfig({
  // ── Entry ────────────────────────────────────────
  entry: ['./src/main.tsx'],        // string | string[]
  outDir: './dist',                  // output directory
  cacheDir: '.sparx/cache',         // SQLite WAL cache location

  // ── Build ────────────────────────────────────────
  build: {
    minify: true,
    sourcemap: 'external',           // 'inline' | 'external' | 'hidden' | 'none' | false
    targets: ['es2022', '>0.5%'],    // browserslist targets
    sideEffects: false,              // enable tree shaking
    chunkSizeLimit: 500,             // KB — warn above this
  },

  // ── Dev server ───────────────────────────────────
  dev: {
    port: 5173,
    hmr: true,
    open: false,
  },

  // ── CSS ──────────────────────────────────────────
  css: {
    modules: true,                   // enable CSS Modules
    framework: 'tailwind',           // 'tailwind' | 'postcss' | 'none'
    lightningcss: true,              // LightningCSS transforms
  },

  // ── SSR / Meta-framework ─────────────────────────
  preset: 'ssr',                     // activate SSR adapter
  ssrEntry: './src/entry-server.ts',

  // ── Security ─────────────────────────────────────
  security: {
    vulnSeverity: 'high',            // 'critical'|'high'|'medium'|'low'|'off'
    secretPatterns: true,            // scan for AWS/Stripe/JWT/GitHub keys
    csp: true,                       // inject Content-Security-Policy
    sri: true,                       // inject Subresource Integrity hashes
    sbom: true,                      // emit dist/sparx-sbom.json
    lockfileAudit: true,             // verify lockfile integrity
    pluginSandbox: true,             // restrict plugin fs/net permissions
  },

  // ── Module Federation ────────────────────────────
  mfe: {
    name: 'host',
    remotes: {
      dashboard: 'http://localhost:3001/remoteEntry.js',
    },
    shared: ['react', 'react-dom'],
  },

  // ── Plugins ──────────────────────────────────────
  plugins: [
    // see plugin reference below
  ],
});

🖥️ CLI Reference

sparx <command> [options]

Security sub-commands

sparx security audit          # full CVE + secret scan
sparx security cve            # CVE-only scan against OSV API
sparx security sbom           # generate SBOM (dist/sparx-sbom.json)
sparx security scan           # scan source for secret patterns
sparx security plugin-audit   # audit plugin sandbox permissions
sparx security headers        # generate security headers manifest
sparx security report         # print full security report
sparx security fix            # auto-upgrade vulnerable lockfile deps

Key options

sparx dev --port 3000 --host 0.0.0.0
sparx build --outDir ./out --sourcemap inline
sparx check --no-types           # skip tsc, only circular check
sparx analyze --json             # JSON output instead of HTML
sparx why react-dom              # trace import chain
sparx inspect --filter src/      # filter dependency graph
sparx ssr --framework remix --port 4000 --prod
sparx verify --ci --strict       # CI mode: exit 1 on any issue
sparx create my-app --framework vue --ts --tailwind

🏗️ Meta-Framework Support

Sparx detects your framework automatically from config files and applies the correct adapter. Use sparx dev and sparx build — no extra setup required.

Example: SvelteKit

// sparx.config.ts
export default defineConfig({
  preset: 'ssr',
  adapter: 'sveltekit',
  entry: ['src/entry-client.js', 'src/entry-server.js'],
});

Example: Remix

export default defineConfig({
  adapter: 'remix',
  entry: ['app/entry.client.tsx'],
  ssrEntry: 'app/entry.server.tsx',
  build: { sourcemap: 'external' },
});

Example: SolidStart (streaming SSR)

export default defineConfig({
  preset: 'ssr',
  adapter: 'solidstart',
  entry: ['src/entry-client.tsx'],
  ssrEntry: 'src/entry-server.tsx',
});

🔌 Plugin Reference

Install any plugin via npm, then add to your config:

npm install -D @sparx/plugin-env @sparx/plugin-pwa

import { envPlugin } from '@sparx/plugin-env';
import { pwaPlugin } from '@sparx/plugin-pwa';
import { iconsPlugin } from '@sparx/plugin-icons';
import { svgPlugin } from '@sparx/plugin-svg';
import { legacyPlugin } from '@sparx/plugin-legacy';
import { compressionPlugin } from '@sparx/plugin-compression';
import { autoImportPlugin } from '@sparx/plugin-auto-import';
import { inspectPlugin } from '@sparx/plugin-inspect';
import { checkerPlugin } from '@sparx/plugin-checker';
import { mockPlugin } from '@sparx/plugin-mock';
import { imagePlugin } from '@sparx/plugin-image';

export default defineConfig({
  plugins: [
    envPlugin({
      prefix: 'SPARX_',             // only expose SPARX_* vars to bundle
      dts: 'src/env.d.ts',          // auto-generate type declarations
    }),
    pwaPlugin({
      manifest: { name: 'My App', short_name: 'App', theme_color: '#000' },
      precache: ['/', '/index.html'],
    }),
    iconsPlugin({
      // use ~icons/mdi/home in any component
    }),
    svgPlugin(),                     // ?url, ?raw, React/Vue component import
    legacyPlugin({
      targets: ['ie 11', 'chrome 60'],  // emits <script nomodule> fallback
    }),
    compressionPlugin({
      brotli: true, gzip: true,     // parallel Rust compression
    }),
    autoImportPlugin({
      imports: ['vue', 'react'],     // auto-inject imports
      dts: 'src/auto-imports.d.ts',
    }),
    inspectPlugin(),                 // UI at /__sparx_inspect__
    checkerPlugin({
      typescript: true,
      eslint: true,
      stylelint: true,
    }),
    mockPlugin({
      routes: { '/api/users': { users: [] } },
      graphql: true,
    }),
    imagePlugin({
      formats: ['avif', 'webp'],
      sizes: [320, 768, 1280],
      quality: 80,
    }),
  ],
});

Plugin capabilities

🔒 Security Pipeline

Sparx has a built-in security gate that runs on every production build.

What it checks

Config example

security: {
  vulnSeverity: 'high',   // block HIGH + CRITICAL CVEs
  secretPatterns: true,
  csp: true,
  sri: true,
  sbom: true,
}

Skip in CI (dev fixtures only)

SPARX_SKIP_SECURITY=1 sparx build   # bypasses all security gates

Never set this in production. It is only for dev fixture builds where node_modules contain dev-only packages with known CVEs.

📦 Module Federation (MFE)

// Host app
export default defineConfig({
  mfe: {
    name: 'host',
    remotes: {
      dashboard: 'http://localhost:3001/remoteEntry.js',
      catalog:   'http://localhost:3002/remoteEntry.js',
    },
    shared: { react: { singleton: true }, 'react-dom': { singleton: true } },
  },
});

// Remote app
export default defineConfig({
  mfe: {
    name: 'dashboard',
    exposes: {
      './Widget': './src/Widget.tsx',
    },
    shared: { react: { singleton: true } },
  },
});

// In host — import from remote at runtime
const Widget = React.lazy(() => import('dashboard/Widget'));

🗺️ Monorepo / Workspace

// sparx.workspace.ts
export default {
  packages: ['packages/*', 'apps/*'],
  build: {
    order: 'topological',      // respect dependency graph
    parallel: true,            // parallel where safe
  },
};

sparx workspaces build        # build all packages in dependency order
sparx workspaces dev          # run dev servers for all packages

📊 Performance Benchmarks

Measured on bare-metal (Node 26.1.0), React fixture:

🧪 Test Status

🔧 Framework-specific Config Examples

⚛️ React

export default defineConfig({
  entry: ['./src/main.tsx'],
  build: { minify: true, sourcemap: 'external' },
  dev: { port: 3000, hmr: true },
  css: { modules: true },
});

🟩 Vue 3

export default defineConfig({
  entry: ['./src/main.ts'],
  build: { minify: true },
  dev: { port: 5173 },
});

🧡 Svelte / SvelteKit

export default defineConfig({
  adapter: 'sveltekit',
  entry: ['src/entry-client.js', 'src/entry-server.js'],
  preset: 'ssr',
  build: { sourcemap: 'external' },
});

💎 SolidStart

export default defineConfig({
  adapter: 'solidstart',
  preset: 'ssr',
  entry: ['src/entry-client.tsx'],
  ssrEntry: 'src/entry-server.tsx',
  security: { vulnSeverity: 'high' },
});

🎸 Remix

export default defineConfig({
  adapter: 'remix',
  entry: ['app/entry.client.tsx'],
  ssrEntry: 'app/entry.server.tsx',
  build: { sourcemap: 'external' },
});

🌌 Astro

export default defineConfig({
  adapter: 'astro',
  entry: ['src/entry.ts'],
  build: { minify: true },
});

🔵 Angular / Analog

export default defineConfig({
  adapter: 'analog',
  entry: ['src/main.ts'],
  ssrEntry: 'src/main.server.ts',
  build: { targets: ['es2022'] },
});

🐛 Troubleshooting

📁 Package Structure

sparx/
├── src/
│   ├── cli.ts                    # CLI entry — 20+ commands
│   ├── commands/                 # analyze, security, ssr, migrate, …
│   ├── build/bundler.ts          # core bundler + security gate
│   ├── config/types.ts           # SparxConfig type definitions
│   ├── dev/devServer.ts          # uWS dev server + HMR
│   ├── meta-frameworks/          # 19 framework adapters
│   └── plugins/inspect/          # inspect UI (/__sparx_inspect__)
├── packages/
│   ├── sparx-security/           # CVE, CSP, SRI, SBOM, secret scan
│   ├── sparx-plugin-{name}/      # 11 official plugins
│   ├── sparx-ssr/                # SSR adapter core
│   ├── sparx-workspace/          # monorepo orchestration
│   ├── sparx-hmr-client/         # browser HMR client
│   └── sparx-module-registry/    # MFE module registry
└── e2e/fixtures/                 # 50+ real framework test fixtures

🤝 Contributing

git clone https://github.com/Avinash-1994/sparx
cd sparx
npm install
npm run build
npm run typecheck      # tsc --noEmit (0 errors expected)
node dist/cli.js dev   # test locally

📄 License

MIT © Avinash-1994