Skip to content
This repository was archived by the owner on Dec 12, 2025. It is now read-only.

CONTRIBUTING.md

Latest commit

 

History

History
59 lines (39 loc) · 3.81 KB

CONTRIBUTING.md

File metadata and controls

59 lines (39 loc) · 3.81 KB

Contributing Guide

Repo setup

This repo uses pnpm to manage monorepo.

  1. Run pnpm install in the repo root folder to install and link dependencies.
  2. Run pnpm run build in the repo root folder to build all packages. You can also do that manually by running pnpm run build in folders packages/react-pages and packages/theme-doc.
  3. Run pnpm run dev in the repo root folder to build and watch all packages. You can also do that manually by running pnpm run dev in folders packages/react-pages and packages/theme-doc. It will rebuild automatically whenever you change the package source code. So we prefer pnpm run dev to pnpm run build when changing source code frequently.

Running playgrounds

cd packages/playground/use-theme-doc/  # or other playgrounds
pnpm run dev
pnpm run build
pnpm run ssr

Notice that the playground import theme-doc from it's src so that we can get hmr when editing theme-doc's source files. This setup should only be used during theme development and it's not for package users.

Debugging

To use breakpoints and explore code execution, you can use the "Run and Debug" feature from VS Code.

  1. Add a debugger statement where you want to stop the code execution.
  2. If you add debugger to the source code of a package, make sure to use pnpm run build or pnpm run dev to build the package after modifying the code.
  3. Click the "Run and Debug" icon in the activity bar of VS Code, which opens the Run and Debug view.
  4. Click the "JavaScript Debug Terminal" button in the Run and Debug view, which opens a terminal in VS Code.
  5. From that terminal, go to packages/playground/xxx, and run pnpm run dev or pnpm run build or pnpm run ssr.
  6. The execution will stop at the debugger statement, and you can use the Debug toolbar to continue, step over, and restart the process...

Running tests

This project uses playwright to run integration tests.

If you are running tests for the first time in this repo, you should run pnpm run install-test-deps in repo root folder to install test deps.

After having test deps installed, run pnpm run test to run all tests. Or run pnpm run test-serve to run tests in vite serve mode only. Or run pnpm run test-build to run tests in vite build mode only. Or run pnpm run test-ssr to run tests in ssr mode only.

Run pnpm run test file-name-filter to filter on file name. For example, pnpm run test hmr will run tests in packages/playground/use-theme-doc/__tests__/hmr.spec.ts.

Adding --debug after any test command will make it run in debug mode. For example, pnpm run test hmr --debug. With this mode enabled, you can play with browser developer tools, exploring selectors, and stop test with await page.pause(). Checkout playwright debug doc to learn more.

Checkout more test arguments at playwright doc. Most notable arguments are:

  • --debug
  • --max-failures=1 make test stop when it encounter the first error, so that you can tackle one problem at a time.
  • --headed
  • --workers=1 prevent playwright using multiple thread to run tests in parallel.

Writing tests

Currently all runnable tests are located at packages/playground/use-theme-doc/__tests__/. You can see them as examples.

Test utils are set up at test-setup/utils/index.ts. They are playwright test fixtures.