Library

Linear homepage

Getting started

The library is both the internal and external API for Code Mode. It is composed of three parts:

1. src/lib - the core React library, with internal and external (user) APIs and widgets
2. src/shared - shared types between lib, node, and external monorepo packages (editor, cli)
3. node - the system level APIs for handling source rewriting, static analysis, etc. via a Vite plugin

Setup

You’ll need to get new secrets and run migrations (from root of the workspace):

pnpm env:secrets:fetch
pnpm migration:run

In addition, open the code-mode-ee branch and find the most recent build-codesandbox task. Click on "Details":

And take the latest templateId from here, and copy it in to server/.env:

For example, SUPERBLOCKS_CODE_SANDBOX_TEMPLATE_ID=6f8q2z

You'll also want to ensure you've compiled the new CLI and library:

pnpm --filter cli --filter library build

Build

Build a copy of the library using pnpm build (from this folder) or pnpm --filter library build (from root of the workspace).

You will continue running pnpm start:ui and pnpm start:server as normal.

Running a code mode app (manually)

1. [Optional] Ensure you've built the latest CLI (only needs to happen if you make changes to the CLI package) a. pnpm --filter cli build
2. Build this library as instructed above
3. Run the CLI2 dev server a. pnpm dev
4. Go to http://localhost:5173

If you make changes to the library, you need to rebuild, reinstall, and rerun the dev server.

Running a code mode app (automated)

A shortcut to above is to run pnpm watch-lib-template from the root of the workspace, which compiles the library and runs the dev server for the active demo app (configured in packages/demo-apps/config.json). This will also watch for changes in the library package and re-build, re-install, and re-run server for you.

Running a code mode app in editor

You'll start by going to the editor at http://localhost:3000/?sb_ff_on=ui.code-mode.enabled and creating a new application, because applications need to be code-mode enabled on create.

By default, when you visit the editor at http://localhost:3000/?sb_ff_on=ui.code-mode.enabled and select a code mode application to edit, it will load the remote CodeSandbox VM. To edit your local copy of a code mode app being run with the CLI2/watch-lib-template, you'll want to enable that via a query flag, ?sb_code_local=true. So you can go to: http://localhost:3000/code-mode/applications/edit/?sb_code_local=true&sb_ff_on=ui.code-mode.enabled.

Development

As you work inside the library, its important to keep in mind that the library contains code for non-editor and editor features.

If you are working on runtime features (adding properties for widgets, adding new widgets, implementing widgets), you'll work directly with those widgets under src/lib/user-facing.

Editor features will typically live under src/lib/internal-details. Keep in mind that we do not want to expose editor features in deployed applications, so you have to ensure widget implementations do not contain editor-only features. This usually means that you'll working under src/lib/internal-details/edit-wrapper.tsx's tree.

Local widget development

If you are just working on widgets implementations without needing to test editor features (for example, doing the initial migration of a widget), you can run the Vite dev server using pnpm --filter library dev. This will load the widgets under src/internal-testing/widgets. You can add your own widget modules that import from the library. See existing implementations for details on how to do so.

Architecture

Vite/CodeSandbox

The code under library/ is a Vite library that builds the React framework (src/lib) and a Vite plugin (node/) used by the CLI2 dev server. The Vite plugin is responsible for handling things like source code updates from visual changes (drag & drop, editor property edits, etc) and static analysis that powers various editor features.

TODO

Scope

The Superblocks concept of scope has been implemented as a library feature. Visit this doc to familiarize yourself with scope and state work in our new framework.

Layouts

Layouts have also changed, so you can see the new details in the layouts doc.

Pages

TODO

Widgets & properties

TODO