Grida is a open source Design tool that aims to provide high-performance, configurable canvas-based editor.

Mission

• Build a high performance interactive graphics engine and its ecosystem

Currently, we have below features / modules.

• canvas
• forms
• database

When entering an unfamiliar directory, always check for README.md and AGENTS.md first. These files contain domain-specific context, conventions, and constraints that override general assumptions. The table below lists the known ones, but sub-directories and individual packages may have their own as well.

Languages

• Node.js 24 LTS - main runtime for most apps
• TypeScript 5 - main language for most apps
• Python 3.12 - partially used for tasks / jobs that are independent (hosted out-of-tree, e.g. gridaco/library)
• Deno - partially used for tasks / jobs, that shares the codebase, e.g. /jobs
• Rust - not in this repo; the graphics engine lives in gridaco/nothing and is consumed as the published @grida/canvas-wasm artifact.

Database

Grida heavily relies on Supabase (PostgreSQL).

• Supabase

Web

• React.js 19
• Next.js 16

UI

• Tailwind CSS 4
• Shadcn UI
• Lucide / Radix Icons

Graphics Backend

• DOM - plain dom as canvas - for website builder canvas. (binded with react)
• Skia - the graphics backend - for 2D graphics, via the prebuilt @grida/canvas-wasm artifact (engine source: gridaco/nothing)

Desktop

• electron with electron-forge
• vite

Tooling

• Turborepo - monorepo build orchestration
• oxfmt (oxc) - code formatter (JS/TS)
• oxlint (oxc) - linter (JS/TS), replaces ESLint
• just - command runner (see justfile at repo root)
• lefthook - git hooks (lefthook.yml)

Documentation files are located in the ./docs directory.

This directory contains the docs as-is, the deployment of the docs are handled by apps/docs. A docusaurus project that syncs the docs content to its directory. When writing docs, the root ./docs directory is the source of truth.

See docs/AGENTS.md for the docs contribution scope (we only actively maintain docs/wg/** and docs/reference/**). When linking docs to editor pages, prefer universal routing (https://grida.co/_/<path>). See docs/wg/platform/universal-docs-routing.md.

The Rust render engine (formerly /crates/*, /format, engine WG docs) lives in the sibling repo gridaco/nothing. This repo consumes it only as the published @grida/canvas-wasm artifact, pinned in editor/package.json and installed from the npm registry. Do not add engine code here.

Importance: Very high

The editor is a monorepo nextjs project that contains the codebase for the editor.

grida.co and [tenant].grida.site domains are connected.

• /editor
  • /app the nextjs app directory, no shared root layout, each has its own root layout.
    • (api)/(public)/v1 contains the public api routes.
    • (api)/private contains the private, editor only api routes.
    • (auth) contains the auth specific flow routes. do not modify.
    • (insiders) contains the insiders, local-only routes. e.g. Grida does not allow email signups, the insiders locally can.
    • (library) contains the Grida Library (open assets) specific pages.
    • (preview) contains the embed-purpose slave preview pages, maily used by the playground.
    • (site) similar to (www), but contains pages that are not seo-purpose.
    • (tenant) contains the tenant-site rendered pages.
    • (tools) contains the standalone tools and editor pages, like playground, etc.
    • (workbench) contains the workbench, the main editor page.
    • (workspace) similar to (workbench), but contains the dashboard, not the actual editor.
    • (www) contains the landing page, seo-purpose static pages. when to add new webpages, this is the root directory.
    • sitemap.ts contains the sitemap.xml generator. this contains the sitemap for the public pages, usually under (www) directory.
  • /www contains the landing page specific components.
  • /components contains the generally reusable components.
  • the shadcn ui primitives + ai-elements live in the @app/ui package (packages/ui), imported as @app/ui/components/* and @app/ui/ai-elements/* (promoted out of /editor/components).
  • /scaffolds contains the feature-specific larger components / pages / editors.
  • /lib contains the core, strictly designed modules with non-opinionated, reusable, and stable modules. - all of them must be worthy to be promoted to <root>/packages directory.
  • /grida-* aims to isolate the modules to a domain-specific scope. once reasonably well-defined, they will be promoted to <root>/packages directory.

Importance: Low

The desktop is a electron app that runs a hosted version of the editor. we choose this way to make things maintainable. We choose electron for stability, consistency, and relies on chrome-specific functions.

Importance: Very high

We use supabase for database, auth, and storage.

• /supabase

  • /functions - we are not using supabase edge functions.
  • /migrations - applied migration sqls.
  • /schemas - human friendly organized schema sqls.

• To run supabase locally, follow the instructions in the supabase docs.

• To suggest a new feature, use supabase migration new <feature-name>.

• To apply migrations, use supabase migration up.

In any cases, bots will never have access to the main (production) database.

Importance: Low

Jobs are hosted on railway.com

Importance: High

monorepo node packages

/packages/grida-canvas-*

Packages that powers the canvas. (some are published to npm, some are not)

Since our project is in a rapid development, some large modules still lives under the /editor directory. Which will progressively move to /packages directory, once things are sorted out and fully defined with the good models.

For each individual package, refer to the README of its own.

We use turborepo (except few isolated packages).

For feature development and UI verification that needs authentication, use local Supabase with insiders auth unless authentication itself is the subject under test. Do not use a hosted Supabase project as the default development backend.

This requires both local Supabase values in editor/.env.local and NEXT_PUBLIC_GRIDA_USE_INSIDERS_AUTH=1. The default seeded account is insider@grida.co / password. Follow CONTRIBUTING.md for the complete setup.

Manual test cases for UX behaviors that are impractical to automate live in test/. When fixing a UX bug or implementing interaction-heavy features, check for relevant TCs there and add new ones when appropriate (see test/AGENTS.md).

To run test, build, and dev, use below commands.

# format the entire repo (JS/TS via oxfmt) — run this regularly, especially before committing
just fmt

# run tests
pnpm turbo test

# run tests for packages
pnpm turbo test --filter='./packages/*'

# build packages (required for typecheck for its dependants)
pnpm turbo build --filter='./packages/*'

# build packages in watch mode
pnpm dev:packages

# run lint (oxlint)
pnpm lint

# run build (all, not recommended)
pnpm turbo build

# run dev
pnpm turbo dev

# run typecheck (always run)
pnpm turbo typecheck # fallback when build fails due to network issues (nextjs package might fail due to font fetching issues)

Important for agents: Formatting and linting run automatically on commit via lefthook pre-commit hooks (oxfmt, oxlint). You can also run just fmt manually. oxfmt is enforced in CI — PRs will fail format checks if code is not formatted. (Rust tooling lives with the engine repo.)

Note: typecheck still rely on packages build artifacts, so it will fail if the build fails. To handle this, you can build the /packages/*, then run typecheck.

pnpm typecheck depends on compiled packages and the editor's Next.js env file. After cloning the repo or installing dependencies, run the following steps before executing pnpm typecheck:

pnpm install

# build shared packages (@grida/canvas-wasm now installs from the npm registry)
pnpm build:packages

# finally, run the repository-wide typecheck
pnpm typecheck

# run test (only packages and editor)
pnpm turbo test --filter='./packages/*' --filter=editor

This project supports git worktrees. When working in a fresh worktree, run the following setup:

# Install node dependencies (no submodules remain in this repo)
pnpm install