vite-plugin-goodscript

Vite plugin for compiling GoodScript files on-the-fly with full Hot Module Replacement (HMR) support.

Installation

npm install --save-dev vite-plugin-goodscript goodscript

Usage

Basic Setup (Any Framework)

// vite.config.ts
import { defineConfig } from 'vite';
import goodscript from 'vite-plugin-goodscript';

export default defineConfig({
  plugins: [
    goodscript({
      level: 'clean',  // Enforce GoodScript "clean" level (TypeScript good parts)
      include: ['**/*-gs.ts']
    })
  ]
});

With React

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import goodscript from 'vite-plugin-goodscript';

export default defineConfig({
  plugins: [
    goodscript({
      level: 'clean',
      include: ['**/*-gs.ts', '**/*-gs.tsx']
    }),
    react()
  ]
});

With Vue

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import goodscript from 'vite-plugin-goodscript';

export default defineConfig({
  plugins: [
    goodscript({
      level: 'clean',
      include: ['**/*-gs.ts']
    }),
    vue()
  ]
});

Options

level

• Type: 'clean' | 'dag' | 'native'
• Default: 'clean'

Language level to enforce:

• 'clean': TypeScript good parts only (Phase 1 restrictions)
• 'dag': Level 1 + ownership/DAG validation (Phase 2)
• 'native': Full validation for native compilation (Phase 3)

include

• Type: string[]
• Default: ['**/*-gs.ts', '**/*-gs.tsx']

Glob patterns for files to process. Only files matching these patterns will be compiled by GoodScript.

exclude

• Type: string[]
• Default: ['node_modules/**']

Glob patterns for files to exclude from processing.

skipOwnershipChecks

• Type: boolean
• Default: false for level 'clean', true for 'dag'/'native'

Skip ownership analysis (Phase 2 checks). Automatically set based on level if not specified.

How It Works

1. Vite intercepts -gs.ts and -gs.tsx files during module resolution
2. GoodScript compiler validates and transforms them on-the-fly
3. Generated TypeScript flows into subsequent plugins (React, Vue, etc.)
4. Full HMR support - changes trigger recompilation and hot reload

Features

✅ Real-time compilation during development
✅ Full HMR support with file caching
✅ Framework-agnostic - works with React, Vue, Svelte, vanilla TS, etc.
✅ Proper error reporting in Vite's error overlay
✅ Zero config for common cases
⚠️ Source maps (coming soon)

Example Project Structure

my-app/
├── src/
│   ├── main-gs.ts          # GoodScript entry point
│   ├── components/
│   │   ├── Button-gs.tsx   # React component in GoodScript
│   │   └── utils-gs.ts     # Utility functions
│   └── legacy/
│       └── old-code.ts     # Regular TypeScript (not processed)
├── vite.config.ts
└── package.json

Migration from CLI Workflow

If you're currently using gsc to pre-compile GoodScript files:

Before (CLI workflow):

{
  "scripts": {
    "build": "gsc && vite build",
    "dev": "concurrently \"gsc --watch\" \"vite dev\""
  }
}

After (Vite plugin):

{
  "scripts": {
    "build": "vite build",
    "dev": "vite dev"
  }
}

The plugin handles compilation automatically - no more generated .ts files cluttering your source tree!

Troubleshooting

TypeScript errors in -gs.ts files

Make sure your tsconfig.json includes the GoodScript type definitions:

{
  "compilerOptions": {
    "types": ["goodscript"]
  }
}

Plugin not processing files

Check that your file patterns match. The default is **/*-gs.ts and **/*-gs.tsx. If you're using different extensions, update the include option.

Performance issues with large projects

The plugin caches compiled results based on file modification time. If you experience slowness:

1. Make sure you're not processing node_modules (excluded by default)
2. Use more specific include patterns to limit processed files
3. Consider using the CLI workflow for production builds

License

MIT

Links

• GoodScript Documentation
• Language Specification
• React Integration Guide
• Issue Tracker