Contribution Guide

Thank you for your interest in contributing to Farm! Farm is currently actively developing version 2.0. We will be introducing numerous new features, expanding ecosystem compatibility, and implementing various optimizations and updates to address current issues. Before submitting your contribution, please make sure to take a moment and read through the following guidelines.

Code of Conduct

All contributors are expected to follow our Code of Conduct.

Bug reports

As farm is currently in the process of rapid development iteration, some unexpected problems may be encountered in the process of development.

We can't fix what we don't know about, so please report problems and unexpected behavior.

You can open a new issue by following new-issues and choosing one of the issue templates.

Feature requests

Please feel free to open an issue using the feature request template.

Pull Request Guidelines

Please adhere to the code style that you see around the location you are working on.
Setup Your Development Environment.
Checkout a topic branch from a base branch, e.g. main .
Run cargo test and make sure that it passes.
If you've changed some packages And prepare for an updated version, you should output npx changeset in the root directory. we should try our best to keep releasing the patch version. If there are no major changes, please choose to update the patch version.
When you are done with your work, verify that it works locally with pnpm run ready

Setup

Branches

main -> Farm v2
v1-main -> Farm v1

Fork and clone the repo.
Create a branch for your PR with git checkout -b your-branch-name.
To keep main branch pointing to remote repository and make pull requests from branches on your fork. To do this, run:
adds a new remote repository named "upstream" that points to the original repository

bash

  git remote add upstream https://github.com/farm-fe/farm.git

retrieves all the branches and their respective commits from the upstream repository that you just configured

bash

  git fetch upstream

sets up tracking between your local main branch and the main branch of the upstream repository

bash

  git branch --set-upstream-to=upstream/main main

Development Environment Setup

Dependencies

Install Rust using rustup.
Node.js version 16+
Pnpm version 8+

IDE

We recommend that you use vscode for development and recommend two necessary plugins that you need to install

rust-analyzer support rust language
biome farm use biome as lint and format the code

You can install them in the extension

Setup Other Dependencies

Start running

Farm development is very simple. You only need to execute pnpm bootstrap in the root directory for development.

npm yarn pnpm bun

npm bootstrap

yarn bootstrap

pnpm bootstrap

bun bootstrap

use pnpm bootstrap to install dependencies and build core packages with series of initialization operations.
Work with examples (open a new terminal): cd examples/refactor-react && pnpm start, report an issue if the example does not start normally.
If examples/refactor-react project runs successfully, the development environment has been configured successfully
If you changed Rust code in crates, run npm run build:rs under packages/core again to get the latest binary.

When you are developing node side code, the root directory executes pnpm start to debug the code in real time, and when you are developing rust side code, the root directory executes pnpm start:rs to debug the code in real time.

npm yarn pnpm bun

npm start   // node side

yarn start   // node side

pnpm start   // node side

bun start   // node side

npm yarn pnpm bun

npm start:rs   // rust side

yarn start:rs   // rust side

pnpm start:rs   // rust side

bun start:rs   // rust side

Testing

We also need to test two parts, a set of Rust tests and a set of Node tests. Make sure all the tests pass before you submit the code.

Rust Testing

Input cargo test in the root directory will run all the test cases.

# root path or crates path
cargo test

Node Testing

Input pnpm test in the root directory to run all test cases based on vitest.

# root path
pnpm test

Quickly create plugins through scaffold

If you want to develop a plugin for farm, farm provides a scaffolding to help you quickly create a plugin, which you can create with the following command. You can go to the cd packages/ cli directory, run npm link or global installation @ farmfe/ cli to use this CLI, after the installation is complete, You can create a plugin through farm plugin create. Farm supports the creation of rust and js plugins.

bash

$ farm plugin create <plugin-name> # create a plugin support js or rust

Pull Request Preface Tip

Farm is divided into two parts: the JavaScript side and the Rust side:

the JavaScript side: see code in the packages directory. contains core (dev server, file watcher, and compiler wrapper), CLI, runtime, and runtime plugins (module system, HMR).
the Rust side: see code in the crates and rust-plugins directory. contains core (compilation context, plugin drivers, etc.), compiler (compile process, HMR update, etc.), and plugins.