Skip to content

Latest commit

 

History

History
230 lines (153 loc) · 6.17 KB

CONTRIBUTING.md

File metadata and controls

230 lines (153 loc) · 6.17 KB
Raw

Contributing

Local development

If you would like to hack on MUI Toolpad or want to run the latest version, you can follow these steps:

If you're looking into contributing to the docs, follow the instructions down below

Prerequisites

  • git
  • node.js

Running apps inside the monorepo (recommended)

This will use the local version of Toolpad as built in the monorepo. This is recommended when your app is in a folder inside of the monorepo. You may even decide to temporarily move your app into the monorepo.

  1. Install dependencies:

    pnpm install

  2. Run the build in watch mode

    pnpm dev

  3. Run Toolpad

    pnpm toolpad dev test/integration/backend-basic/fixture/toolpad --dev

    Note: It's important to note the difference between pnpm toolpad dev and the --dev parameter. The first instruction runs Toolpad in dev mode. The --dev parameter is one for contributors only and runs the underlying next.js app that powers the editor in dev mode. The latter makes sure the development build of React is being used and the editor frontend application runs in watch mode.

If your application has dependencies other than @mui/toolpad, you have to temporarily add it to the workspace:

  1. update pnpm-workspace.yaml (in the workspace root, not in your app), add your app folder to workspaces.packages. e.g. for examples/qr-generator which has a dependency on qrcode this would be:

    packages:
  - 'packages/*'
  - 'docs'
  - 'test'
  - 'examples/qr-generator'

    You should also run pnpm dev as follows to avoid the dev scripts from kicking in

    pnpm dev --ignore qr-generator

  2. Run

    pnpm install

  3. Make sure to start the build in watch mode again and the run the app with

    pnpm toolpad dev examples/qr-generator --dev

Linking Toolpad in a folder on your system (advanced)

Expand instructions

In some cases you may want to link local toolpad into a project on your laptop.

  1. Install dependencies:
pnpm install

  1. Run the build in watch mode

    pnpm dev

  2. In another folder, start a toolpad project using:

    {
  "name": "toolpad-local",
  "version": "1.0.0",
  "license": "MIT",
  "scripts": {
    "dev": "toolpad dev --dev",
    "build": "toolpad build --dev",
    "start": "toolpad start --dev"
  },
  "dependencies": {
    "@mui/toolpad": "portal:<your-local-toolpad-monorepo>/packages/toolpad-app"
  },
  "resolutions": {
    "@mui/toolpad": "portal:<your-local-toolpad-monorepo>/packages/toolpad-app",
    "@mui/toolpad-core": "portal:<your-local-toolpad-monorepo>/packages/toolpad-core",
    "@mui/toolpad-components": "portal:<your-local-toolpad-monorepo>/packages/toolpad-components",
    "@mui/toolpad-utils": "portal:<your-local-toolpad-monorepo>/packages/toolpad-utils"
  }
}

    1. Replace <your-local-toolpad-monorepo> with the path to the toolpad monorepo on your file system. Make sure to keep portal:.

    2. In order to use portal: dependencies, we will need to use pnpm 2. So start by running

      pnpm set version berry

      and add to the .pnpmrc.yml:

      nodeLinker: node-modules

    3. then run

      pnpm install

  3. Run start toolpad in dev mode:

    pnpm dev

Running integration tests

The playwright tests can be run in one of two modes:

  1. Build the production target, then run the integration tests in production mode:

    pnpm release:build
pnpm test:integration --project chromium

  2. Toolpad in dev watchmode and run the integration tests in dev mode with the TOOLPAD_NEXT_DEV environment variable (slower)

    pnpm dev
TOOLPAD_NEXT_DEV=1 pnpm test:integration --project chromium

Use the --ui flag to run the tests interactively.

Building and running the documentation

  1. If you haven't already, install the project dependencies using

    pnpm

  2. To start the documentation application in dev mode run

    pnpm docs:dev

    If all goes well it should print

    ready - started server on 0.0.0.0:3003, url: http://localhost:3003

  3. Open the docs application in the browser http://localhost:3003/toolpad

Reviewing PRs

  • Check out the PR branch locally with your tool of choice (GitHub Docs)

  • Run to build the project

    pnpm && pnpm release:build

  • Run it on your project of choice

    pnpm toolpad dev /path/to/my/toolpad/project

Using CodeSandbox CI

Each pull request is built on CodeSandbox CI. As a result of that we have a published Toolpad package for ever pull request. To use the package from the pull request, take the following steps:

  1. In the GitHub PR checks, locate the ci/codesandbox check and make sure it has successfully finished building. Click on "details" to open the CodeSandbox CI user interface.

  2. In the codesandbox UI, on the right panel, locate and expand the "Packages (6)" section.

  3. Right click the link named @mui/toolpad and copy the address

    Copy CodeSandbox CI package link

  4. In your package.json, for the @mui/toolpad dependency, replace the version with aforementioned link. e.g.

    "dependencies": {
   "@mui/toolpad": "https://pkg.csb.dev/mui/mui-toolpad/commit/<commit>/@mui/toolpad"
}

  5. Run

    pnpm --force

You'll now be able to explore your project with the Toolpad version from the GitHub PR.

Sending a pull request

Please have a look at our general guidelines for sending pull requests.

Release process

See RELEASE.md