vite-plugin-jscad

vite-plugin-jscad is a model preview development server and bundler for JSCAD models. Models written in TypeScript (TSCAD) or JavaScript using ESM (import syntax) are supported.

• Preview server: The preview server provides a live view of your model. It's just a website running locally, so you can open it in any browser. It's fully interactive. As you save changes to your model, the preview will be updated in realtime while maintaining your camera position or zoom level. The feedback cycle is lightning fast.
• Bundler: The bundler compiles your model into a JavaScript file that can be read by the jscad CLI for transformation into an output format like STL. This is particularly useful if you want to write your models in TypeScript instead of plain JavaScript.

Setup

Setup is straightforward:

1. (Optional) Set up TypeScript by creating a tsconfig.json file by running npx tsc --init

2. Install Vite in your project by running npm install --save-dev vite

3. Install the plugin with npm install --save-dev vite-plugin-jscad

4. Configure the plugin. Create a vite.config.ts file with the following contents:

   import type {UserConfig} from "vite";
   import {jscadPlugin} from "../plugin/vite-plugin-jscad";
    
   export default {
     plugins: [jscadPlugin()]
   } satisfies UserConfig

   If using plain JS without TypeScript, create vite.config.js instead:

   import {jscadPlugin} from "../plugin/vite-plugin-jscad";
    
   export default {
     plugins: [jscadPlugin()]
   }

Configuration

The only configuration option is the path to your model file. This can be inferred automatically:

• First, it will look for build.lib.entry in your Vite config
• Then it will look for main in your package.json
• Finally, it will look for index.js or index.ts in your project root

If none of these apply for you, you'll need to pass the module file path explicitly to jscadPlugin:

jscadPlugin({moduleFile: "path/to/file.js"})

Usage

Preview server

To run the preview server, run:

npx vite

Then open the given localhost URL in your browser. You can customize which port it runs on by setting server.port in your config file.

To see changes, simply edit your model file and save it.

If you are using VSCode, the built-in browser can provide a convenient preview without installing any exensions. Simply press Cmd/Ctrl+Shift+P to open the command palette and type "Open Port In Browser", then enter the preview port (5173 by default).

Bundling and compiling models

To bundle your model, run:

npx vite build

Then you can compile your model using the JSCAD CLI:

# Assuming your file is named index.ts
npx jscad dist/index.js -o index.stl

For convenience, you may want to combine these into a single script in your package.json file:

{
  "scripts": {
    "start": "vite",
    "build": "vite build && jscad dist/index.js -o index.stl"
  }
}