Engraft

Engraft is an API that brings rich interactive tools into open-ended programming environments. Welcome!

Getting started

The easiest way to start using Engraft is Graft Garden, a hosted web-app where you can create and share programs.

Engraft also has a range of embeddings so that live & rich tools can be brought to where you are already working:

• Engraft in React (useEngraft)
• Engraft at the command-line

A few other demos can be found at engraft.dev.

Building on the Engraft API

Do you want to build a tool that can be embedded inside Engraft programs? See [TODO: component dev guide].

Do you want to make your application or programming environment extensible with Engraft tools? See [TODO: host dev guide].

Development

This section is about how to work in this repository.

Setup

First, install external prerequisites:

1. node: Not sure which version range is supported but for the record v19.7.0 works fine. (We recommend nvm for managing node installations.)
2. yarn 1.x: On Mac, brew install yarn will take care of this.

Next, from the base of the repository, run:

1. yarn to install dependencies,
2. yarn testbed:dev to start a testbed development server (after building necessary packages).

Codebase overview

Code is divided into separate packages located in the packages directory. Each will be (TODO!) hosted on the npm registry as @engraft/PACKAGE-NAME. Here's a quick (non-exhaustive) overview:

• Core
  • core: Defines the Engraft API itself and infrastructure common to all of Engraft (like EngraftPromise).
  • refunc: Defines Refunc, Engraft's system for incremental computation.
    • refunc-react: Helpers connecting Refunc with React.
    • eslint-plugin-refunc-hooks: ESLint plugin ensuring proper use of Refunc hooks.
  • core-widgets: A few visual elements that seem to be central to the Engraft experience, such as displaying values, var tokens, etc. Its long-term identity remains to be seen.
• Tool development
  • toolkit: Your one-stop shop for tool development – should be the only package most tools need to import from @engraft.
• Host development
  • hostkit: Your one-stop shop for host development – should be the only package most hosts need to import from @engraft.
  • fancy-setup: Actually, hosts will probably also need to import this package. It contains a setup (EngraftContext) with all the tools built by the Engraft team. This is probably not the way things will work long-term.
  • basic-setup: If you run into trouble, you may want to use this smaller package. It excludes a few components which are real big or cause trouble. (Again: probably not a long-term thing.)
• Tools
  • tool-*: Each of these packages defines a tool maintained by the Engraft team.
  • original-tools: A bunch of tools that haven't been sorted into packages yet. (Provisional.)
• Hosts
  • graft-garden: Our iconic web-app Engraft host.
  • cli: For running Engraft as a process, at the command line or as a subprocess.
  • use-engraft: A React hook for using Engraft to define computations in React web-apps.
    • use-engraft-demo & use-engraft-demo-js: Illustrations of useEngraft embedded into simple React web-application codebases (in TypeScript and JavaScript, respectively).
  • testbed: Testbed used in Engraft development.
• Utilities
  • shared: An assortment of utilities shared across this codebase. It should not be used outside this monorepo.
  • update-proxy: A helper that makes it easy to perform immutable updates, used often in tools.
  • codemirror-helpers: Extensions to CodeMirror, including FancyCodeEditor (which powers slot, text, python, etc.).

Build system overview

Most packages (including those defining Engraft components) are libraries. In their package.json files, they provide build-lib scripts which compile TypeScript from src into JavaScript in lib (with TypeScript declaration files and various source maps).

For a package to be compiled correctly, its dependencies must be compiled, and their dependencies, and so on. We use Lerna/nx to manage all of this automatically. To build a library and all its n-fold dependencies, run:

yarn lerna run build-lib --scope @engraft/PACKAGE-NAME

(This is admittedly a mouthful and we may make some shortcuts.)

Some packages define applications. For these, use build-app rather than build-lib. This will call Vite to bundle all our interdependent modules into JavaScript that can be loaded by the browser.

Testing & other checks

We have tests (run by Vitest) and a few other ways of checking that things are working (TypeScript, ESLint, depcheck). These should all be documented more (TODO!), but for now, just run

yarn all:checks

and make sure there aren't any errors.

Editors

Engraft has primarily been developed with VS Code, with the ESLint extension. With this setup, TypeScript language services and inline linting feedback work nicely.