Skip to main content

Installation

FluidCAD ships as a desktop app for Windows, Linux and macOS, and as an npm package for running it from a Node.js project in your browser. Pick the download for your system below, or skip to the npm installation if you prefer to work from a terminal.

Models are .part.js files (parts) and .assembly.js files (assemblies), written by the viewport as you work.

The links below point at the current release, FluidCAD 0.0.46; every build is also on the GitHub releases page. The app updates itself from there afterwards: it checks quietly in the background and installs the next version when you quit.

Windows​

Run the installer and follow the prompts. The installer is not code-signed, so Windows SmartScreen shows Windows protected your PC on first launch; choose More info → Run anyway.

Linux​

For the AppImage, mark it executable (chmod +x FluidCAD-*.AppImage) and run it. For the .deb, install it with sudo apt install ./FluidCAD-*.deb. The AppImage updates itself; the .deb is updated by installing the next release's package.

macOS​

Open the disk image and drag FluidCAD into Applications. The build is signed and notarized, so it opens without a Gatekeeper prompt.

npm installation​

If you would rather run FluidCAD from a terminal and model in your browser, run it with npx: on its own for the start screen, or inside a project to open just that one.

Prerequisites​

  • Node.js version 24 or higher
  • npm (comes with Node.js)

The start screen​

npx fluidcad

opens the start screen in your browser, the same one the desktop app shows: your recent projects, New Project, Open Project, and the engine each project runs on. Each project opens in a tab of its own. Leave the command running while you work; Ctrl+C stops FluidCAD and every project it opened. See fluidcad in the CLI Reference.

Create a new project​

To set a project up from the terminal instead:

mkdir my-hinge && cd my-hinge
npm i fluidcad
npx fluidcad init
npx fluidcad serve

init creates a project with the following structure:

my-hinge/
├── package.json
├── jsconfig.json
├── fluidcad.json       ← project configuration (engine pin, unit)
├── init.js             ← required project entry point
└── part1.part.js       ← your first part, empty

serve starts the FluidCAD server and opens the viewport in your browser. Leave it running while you model; press Ctrl+C to stop it.

FlagDescriptionDefault
-w, --workspace <path>Path to your projectCurrent directory
-p, --port <port>Server port — if it's already taken, the next free one is used3100
--no-openDon't launch a browser — for CI and remote sessionsopens by default

To run from elsewhere, point -w at your project: npx fluidcad serve -w ./my-app.

fluidcad.json records which FluidCAD version the project was authored against and, optionally, its default length unit. See Project configuration.

note

FluidCAD model files use the .part.js extension (assemblies use .assembly.js). The viewer only picks up files with this naming convention.

note

FluidCAD is installed per-project and run with npx fluidcad …; a global install (npm install -g fluidcad) is not supported. The engine and your editor's type hints both resolve from the project's node_modules, so the package must live there. If you see Cannot find module 'fluidcad' imported from …, run npm i fluidcad inside the project.

The init.js file​

Every FluidCAD project must have an init.js file at its root. It initializes the engine and must be present before any .part.js file can run:

import { init } from 'fluidcad';

export default await init();

Do not modify this file — it is generated by npx fluidcad init and is required for the viewer to work. Project configuration covers what it does and what else lives in the project folder.

The starter file​

Open part1.part.js. This is the file that was generated for you, and it is the part the viewport opens on when the server starts:

import { part } from 'fluidcad/core';

export const part1 = part('Part 1', () => {
});

part('Part 1', () => { ... }) declares a named part and exports it as part1. Everything inside the callback builds that part, and the export is what an assembly would later insert(). The callback is empty, so the viewport is too: every sketch and feature you add, from the toolbar or in code, lands inside it and becomes a row in the History panel.

Rename the file and the part to what you are building; Parts covers the convention.

Beyond serve​

The same CLI writes STEP, STL, and PNG files without opening the UI, and runs the MCP server that lets AI agents drive your workspace:

npx fluidcad export step                     # every shape → <entry>.step
npx fluidcad export png --view front --open

See the CLI Reference for every command and flag, or run npx fluidcad --help.

Editor setup​

FluidCAD runs on its own — no editor required. If you'd rather keep modelling in the editor you already use, it also ships official extensions for VS Code and Neovim. Every option drives the same engine and the same live 3D viewport; pick whichever fits your workflow.

The desktop app, npx fluidcad and npx fluidcad serve all open the whole product: the 3D viewport, every interactive modelling tool, and a code editor with completion driven by the engine's own type declarations — so extrude( shows its signature and edge().onPlane( completes, always matching the version you're running.

The code editor stays hidden until you ask for it. Open it from the ☰ menu or with Ctrl+B; it takes width from the left, so the model narrows rather than being covered. Files are tabs in the top bar, added with + — there's no file tree, because the editor already knows about every file in the workspace.

VS Code​

  1. Install the FluidCAD extension from the VS Code Marketplace.
  2. Open your project folder in VS Code.
  3. Open the Command Palette (Ctrl+Shift+P on Windows/Linux, Cmd+Shift+P on macOS) and run Show FluidCAD Scene.

A 3D viewport opens in a side panel. It updates live as you edit any .part.js file.

Neovim​

Add the plugin with lazy.nvim:

{
  "Fluid-CAD/FluidCAD",
  config = function()
    require("fluidcad").setup()
  end,
  ft = { "javascript" },
}

Open a .part.js file — the server starts automatically. Run :FluidCadOpenBrowser to open the 3D viewport in your browser.

Any other editor​

npx fluidcad serve works alongside any editor too: leave the browser tab on the viewport and edit .part.js in whatever you prefer — the model rebuilds on save. Opening the same file in two editors at once is the one thing to avoid.

Next​

Getting started builds a butt hinge from an empty part to an animated assembly, one tool per step.