Introduction

The React API provides bindings for /docs/api/classcad#classcad. It makes it easier to use the API in a reactive context and with components specifically. For the most part it helps you to manage and access drawing across the component tree.

npm install @buerli.io/react

Types

It consists of only one hook useClassCAD.

type ClassCADReturn = {
  /** The ClassCAD API */
  api: ClassCADApi
  /** The classcad drawing */
  drawing: ClassCAD
  /** The drawingId of the instance */
  drawingId: DrawingID
  /** Renderable component that ties a @buerli.io/react BuerliGeometry to the drawing instance */
  Geometry: (props: BuerliGeometryProps) => JSX.Element
}

useClassCAD(name: string): ClassCADReturn

Usage

You must call init before you can use the classcad API. You should do this in the root of your application.

import { useEffect } from 'react'
import { Canvas } from '@react-three/fiber'
import { useClassCAD } from '@buerli.io/react'
import { init, WASMClient } from '@buerli.io/classcad'

// Get your app key from https://www.classcad.ch/user
const appKey = '...'
init((drawingId) => new WASMClient(drawingId, { appKey }))

Then you can use the classcad API and other functionality in your components.

function App() {
  const { drawing, drawingId, api, Geometry } = useClassCAD()
  ///...
}

Managing ClassCAD drawings

useClassCAD automatically connects to and manages a ClassCAD drawing instance. Each instance is identified by a string, which by is "default" if you do not provide one, as in useClassCAD("default"). You use this identifier to access the same instance across different components.

If all components using the same identifier unmount, the instance will automatically be disconnected and freed.

function Foo() {
  const { api } = useClassCAD('main')
  ...

function Bar() {
  // This will access the same instance as Foo
  const { api } = useClassCAD('main')
  ...

function Render() {
  const { Geometry } = useClassCAD('main')
  // This will render the outcome of the "main" session
  return <Geometry />

You can also create multiple instances:

function SessionA() {
  const { api } = useClassCAD('A')
  ...

function SessionB() {
  // This is a different session than SessionA
  const { api } = useClassCAD('B')
  ...

API

.drawing

The ClassCAD drawing instance. See /docs/api/classcad#classcad for more details.

.drawingId

The drawingId of the instance. This is a unique identifier.

.api

api contains all the ClassCAD commands. You can call it in events, effects, or anywhere you like. It contains apis for parts, assemblies, geometries, and more. You can find the full API documentation here.

All commands are async and return a promise with the same structure, which contains a result, which usually is an ID, and messages which are used for error-handling. Commands will throw an error if the messages array contains any messages with a level greater than 0. The maxLevel is the maximum level of the messages, which can be used to determine if there are any errors.

Promise<{
  result: number | null
  messages?: {
    message: string
    level: number
    code: number
    api: string
  }[]
  maxLevel?: number
}>

A simple example.

function Box({ width = 100, length = 100, height = 100 }) {
  const { api } = useClassCAD("box")
  useEffect(() => {
    // This will create a box
    async function run() {
      // See https://classcad.ch/docs/API/part
      const { result: part } = await api.v1.part.create({ name: 'Part' })
      await api.v1.part.box({ id: part, width, length, height })
    }
    run()
  }, [])
  ...
}

.Geometry

You have created geometry in Buerli, but you want to show it in your THREEJS app. Geometry is a renderable @react-three/fiber component that is primed to a drawings state. It will automatically update when the drawing changes, and it will also handle the loading state via suspense. You need to render this component in a react-three-fiber Canvas.

function Scene() {
  const { Geometry } = useClassCAD('box')
  return <Geometry />
}

function App() {
  return (
    <Canvas>
      <Scene />
    </Canvas>
  )
}