generator-jscad

Create a jscad project

Installation

First, install Yeoman and generator-jscad using npm (we assume you have pre-installed node.js).

npm install -g yo
npm install -g generator-jscad

Then generate your new project:

yo jscad

You can select the type of project you want to build. A single object project is the default. You can create a multi object project with selection via a dropdown list or a set of check boxes. These are more complex, but allow you to organize and view a much larger project.

You can also create a VitePress site with a live viewer.

Running

The jscad project uses gulp to create a dist directory and watches your source for changes. To view your model during development, you can use one of the following options:

Development Environment (tmux)

If you have tmux and jscad1-server installed globally, start-dev.sh launches both panes in a single tmux session — npm start on the left watching for file changes, and jscad1-server on the right serving the model:

./start-dev.sh

The script will error with install instructions if either tmux or jscad1-server is missing. To install the global dependency:

npm install -g jscad1-server

Once running, open http://localhost:3000 and load the dist file. Any time you save a source file, gulp rebuilds the dist file automatically.

Local JSCAD Server (Recommended)

Run jscad1-server locally to preview your model in real-time:

npm install -g jscad1-server
jscad1-server

Then navigate to http://localhost:3000 and load the dist file by dragging it into the OpenJsCad browser.

VitePress Documentation Preview

Alternatively, you can build and preview the documentation site with a live model viewer:

npm run docs:build && npm run docs:preview

start

npm start or npm run start will launch gulp and watch for file changes, recreating the dist file on each save.

clean

Deletes the dist directory when you run npm run clean.

inject

Run gulp to combine the source files and inject the dependent libraries with npm run inject. Libraries are found using a gulp plugin that looks for a jscad.json file in a package. These files are combined and minimized before injecting into the dist file.

build

Build the VitePress static site by running npm run build. This script combines the readme with a vue-openjscad component to display a live view of the model. When hosted on GitLab, the .gitlab-ci.yml CICD file uses this script to publish to GitLab Pages.

serve

Run VitePress in dev mode with npm run serve. This script watches for file changes and hot reloads changes made to the README file. Changes to the model are not automatically reloaded; a manual reload is required.

jscad-utils

The example project uses jscad-utils. This is a set of utilities that make object creation and alignment easier. To remove it, npm uninstall --save jscad-utils.

Sharing Your Model

To share your model publicly, publish the VitePress site by running npm run build and deploying the generated output. This produces a static site with a live interactive viewer embedded directly in the page.

Hosting on GitLab Pages is handled automatically by the included .gitlab-ci.yml CICD pipeline. For GitHub, the build output can be deployed via GitHub Pages.

jscad1-server is a local development tool only and cannot be used to share models.

License

MIT © John Cole