Visual Canvas — Customer guide

Visual Canvas is a visual website builder: drag blocks onto the canvas, edit text and styles, manage pages, and export HTML. This guide walks you from a clean machine to a running app and explains every major feature.

System requirements

  • Computer: macOS, Windows, or Linux with a modern 64-bit system.
  • RAM: at least 8 GB recommended for a smooth browser + dev server experience.
  • Browser: latest Chrome, Firefox, Safari, or Edge for using the builder.
  • Node.js: version 18.x or newer (20 LTS is ideal) — required to install dependencies and run the dev server.
  • npm (bundled with Node) or compatible package manager (pnpm / yarn if you prefer — commands below use npm).
  • Editor (optional): VS Code or any text editor if you need to change project files.
  • Terminal: Terminal.app, PowerShell, Windows Terminal, or integrated terminal in your editor.

Install Node.js

Node.js runs the tooling that downloads libraries (node_modules) and starts the local preview server.

Option A — Official installer (simplest)

  1. Open https://nodejs.org.
  2. Download the LTS version for your OS.
  3. Run the installer and accept defaults unless your organization specifies otherwise.
  4. Restart your terminal.

Verify installation

Open a terminal and run:

node -v
npm -v

You should see version numbers (e.g. v20.x.x and 10.x.x). If command not found, Node is not on your PATH — reinstall or fix PATH.

Option B — Version managers (advanced)

Teams often use nvm (macOS/Linux) or nvm-windows to switch Node versions per project. Follow the official nvm README, then nvm install --lts and nvm use --lts.

Get the project on your machine

You need the application folder (the Visual Canvas / JBuilder project root). How you receive it depends on your team:

  • ZIP / drive: Unzip to a folder you can find, e.g. ~/Projects/JBuilder.
  • Git: Clone the repository, then cd into the repo root (where package.json lives).

The project root must contain at least:

  • package.json — lists dependencies and scripts.
  • package-lock.json (or lockfile for your package manager) — pins exact versions.
  • src/ — application source code.
  • vite.config.ts — build tool configuration.
Always run install and dev commands from this root folder — the same directory as package.json.

Install dependencies (node_modules)

JavaScript projects list libraries in package.json. Installing downloads them into node_modules/ (often hundreds of megabytes — this is normal).

Steps

  1. Open a terminal.
  2. cd to the project root (folder containing package.json).
  3. Run:
npm install

Wait until it finishes without errors. First run may take several minutes depending on network speed.

What npm install does

  • Reads package.json and package-lock.json.
  • Downloads packages into node_modules/.
  • May run post-install scripts defined by dependencies.

If you use another package manager

  • pnpm: pnpm install
  • yarn: yarn

Stick to one manager per project to avoid conflicting lockfiles.

Common issues

  • EACCES / permission errors: Do not use sudo npm install on personal projects; fix npm’s default directory or use a node version manager.
  • SSL / corporate proxy: Your IT team may need to configure npm proxy or certificates.
  • Delete and retry: Remove node_modules and run npm install again only if instructed — it forces a full reinstall.

Feature locks (optional .env)

Some deployments ship a trial or limited build of Visual Canvas. Your administrator controls this with environment variables in a file named .env at the project root (same folder as package.json). Values are read when you run npm run dev or npm run build — restart the dev server or rebuild after changing them.

Start from the template: copy .env.example to .env, then edit. The example file lists every variable with short comments.

Purchase flag

  • VITE_PURCHASE_UNLOCKED=true — full product: every VITE_LOCK_* below is ignored (recommended for internal or licensed use).
  • VITE_PURCHASE_UNLOCKED=false — treat the build as not purchased. Each lock below can then hide or block specific actions.

Lock flags (only matter when purchase is false)

Set a variable to true to block that feature and show a purchase message (toast or inline). Set to false to leave the feature available even without purchase.

  • VITE_LOCK_FILE_UPLOAD — Assets: no “Choose files” or drag-and-drop upload to the local library.
  • VITE_LOCK_EXPORT — Toolbar export of the current page as a ZIP.
  • VITE_LOCK_SAVE_PROJECT — Save project to JSON and browser auto-save.
  • VITE_LOCK_VIEW_SOURCE — Canvas “Source” / full-page HTML editor.
  • VITE_LOCK_EXPORT_ALL_ZIP — Page Manager “Export all” multi-page ZIP.
  • VITE_LOCK_IMPORT_PROJECT — Import project from a JSON file.

Custom message

Optional: VITE_PURCHASE_CTA_MESSAGE — text shown when someone hits a locked action (for example a link to your pricing page). If omitted, a default message is used.

To enable the full product for customers, set VITE_PURCHASE_UNLOCKED=true in .env and rebuild. You do not need to delete the VITE_LOCK_* lines; they are ignored while purchase is unlocked.

Run the application (development)

After a successful install, start the local development server:

npm run dev

The terminal prints a local URL, typically http://localhost:5173 (Vite default). Open that URL in your browser.

  • Hot reload: Saving source files refreshes the app automatically in many cases.
  • Stop the server: Press Ctrl+C in the terminal (Mac: same in most terminals).

Other useful scripts (from package.json)

  • npm run build — production build to dist/.
  • npm run preview — serve the production build locally to test.
  • npm run lint — run ESLint (for developers; optional for pure content work).

Build your first page (happy path)

  1. Start npm run dev and open the app URL.
  2. You should see the builder workspace: canvas in the center, side panels for components and properties.
  3. Open Templates (toolbar) and hover a card — click Use Template to load a full starter page.
  4. Click a block on the canvas to select it; the Properties panel updates — change text, colors, or spacing.
  5. Drag a component from the library onto the canvas or into a layout column/stack.
  6. Use Pages (workspace strip) to add another page if available.
  7. Use Export or preview actions from the toolbar when you want HTML output.

This gives you a complete loop: template → edit → add blocks → export.

Interface tour

Toolbar (top)

Usually includes: page title, templates, device preview widths, undo/redo, export, AI toggle, asset tools, and other actions. Exact buttons depend on your build.

Component sidebar

Palette of draggable blocks (heroes, forms, footers, layouts, etc.). Drag onto the canvas or into a compatible drop zone (e.g. grid columns).

Canvas

Live preview of the page. Click to select; selected blocks show handles or outlines. Nested layouts may accept child blocks.

Properties panel

Contextual editors for the selected block: content fields, style controls, sometimes layout options.

Pages / workspace strip

Switch between pages, add or rename pages depending on UI version.

Components library

  • Components are grouped by category (navigation, hero, forms, etc.).
  • Drag a component to the canvas. Some layouts only accept drops in specific zones.
  • After placing, select the block and edit props in the properties panel.
  • Complex types (e.g. pricing tables, galleries) ship with default content you can replace.

Templates

Templates replace the current page’s root blocks with a pre-designed stack (navigation, hero, sections, footer).

  • Open the template gallery from the toolbar.
  • Browse by category; premium badges may appear for certain designs.
  • Applying a template overwrites the page content for that page — save or duplicate first if you need the old version.

Canvas, selection, and nesting

  • Select: Click a block. Parent layouts may show nested children — click carefully or use hierarchy if your UI exposes it.
  • Reorder: Drag handles or drag-and-drop within the canvas where supported.
  • Layouts: Grid and stack layouts divide space into columns or vertical regions; drop targets highlight when valid.
  • Freeform / pinned elements: Some builds allow absolute positioning for overlays — follow on-screen cues.

Properties panel

When a block is selected, you can typically edit:

  • Text content (headlines, body, button labels).
  • Links and URLs.
  • Colors, spacing, typography (depending on block type).
  • Lists (nav links, features, pricing tiers) where the component supports arrays.

If a field is missing, that block type may not expose it — choose a different component or ask your development team to extend definitions.

Pages and workspace

  • Multi-page sites let you maintain separate canvases per page.
  • Add a page from the workspace UI when available; name pages clearly for export and handoff.
  • Switching pages does not auto-save unless the product implements persistence — confirm with your deployment (local vs hosted).

Preview and device widths

Use toolbar breakpoints (desktop / tablet / phone) to check responsive behavior. The canvas reflows according to CSS; very wide fixed elements may need manual adjustment in properties.

Assets and images

Many builds include an asset manager:

  • Upload images from your computer (subject to validation rules).
  • Library / stock / remote tabs may offer curated or external images depending on configuration.
  • Assign images to hero backgrounds, galleries, avatars, etc., via component props or pickers.

Exporting HTML

  • Export generates static HTML (and related assets/CSS depending on implementation) for the current page or site.
  • Use exported files to host on any static host or hand off to developers for integration.
  • Some blocks may export simplified markup compared to the live React canvas — complex interactions might need manual follow-up.

AI assistant (Visual Canvas)

If enabled in your build, the assistant helps with quick actions:

  • Suggestion chips and prompts may insert layout blocks or adjust styles when a block is selected.
  • Read assistant messages — some actions require a selected block (e.g. color or layout tweaks).
  • The assistant is rule-based in many setups, not an open-ended chat with a live model — expectations should match your product version.

Production build

To create optimized files for deployment (hosting the builder app itself, not the exported customer sites):

npm run build

Output goes to dist/. Preview locally:

npm run preview

Serve dist/ with any static file server or your organization’s CI/CD pipeline.

Troubleshooting

Blank page or errors in browser

  • Check the terminal for compile errors; fix red errors before relying on the UI.
  • Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac).

npm install fails

  • Confirm Node 18+.
  • Try clearing npm cache: npm cache verify (advanced: npm cache clean --force only if needed).
  • Corporate networks: ask IT about registry access and proxies.

Port already in use

Another process uses 5173. Close it or configure Vite to use another port (developer task in vite.config.ts).

Changes not visible

  • Ensure you saved files and the dev server is running.
  • Confirm you are editing the correct project folder.