# Library

[Linear homepage](https://linear.app/superblocks/project/code-mode-11e3f2bd8edb/overview)

## 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
1. `src/shared` - shared types between lib, node, and external monorepo packages (editor, cli)
1. `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
```

### 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`
1. Build this library as instructed above
1. Run the CLI2 dev server
   a. `pnpm dev`
1. Go to [http://localhost:5173](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](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](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/<app id>?sb_code_local=true&sb_ff_on=ui.code-mode.enabled](http://localhost:3000/code-mode/applications/edit/0edce541-c7bd-4862-8d16-d8bd80b23384?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](/packages/library/src/lib/user-facing/state-timers-apis.md) 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](/packages/library/src/lib/user-facing/layout.md).

### Pages

TODO

### Widgets & properties

TODO