Version: 0.15

Create A Project

In this chapter, we will create a new Farm React project from scratch, and launch it in development mode.

note

In this tutorial, we use pnpm as default package manager. This chapter is build a Farm react project from scratch, If you are trying to init a new Farm Project rapidly, use our official template with command pnpm create farm.

Create A Package

First we execute pnpm init to create a new package.

mkdir farm-react && cd farm-react && pnpm init

A package.json file will be autogenerated.

Install Dependencies

Install necessary dependencies:

react and react-dom:

pnpm add react react-dom && pnpm add react-refresh @types/react @types/react-dom -D

farm related dependencies:

pnpm add -D @farmfe/cli @farmfe/core @farmfe/plugin-react

There are 3 packages that are necessary for a react project:

@farmfe/cli: This package provides commands like farm start, farm build, farm preview, it must be used with @farmfe/core and can not be used separately.
@farmfe/core: This package provides Compilation and Dev Server abilities, provides all necessary component for local development and product build. It exports Compiler, DevServer and Watcher, which is used for compile the project, serve the project in development mode and watch the project for Hot Module Replacement.
@farmfe/plugin-react: This package provides abilities for React Jsx compilation, and react-refresh support.

Create Farm Config File

Create a farm.config.ts file under project root:

.
├── farm.config.ts
├── package.json
└── pnpm-lock.yaml

and add following configuration:

import { UserConfig } from '@farmfe/core';

function defineConfig(config: UserConfig): UserConfig {
  return config;
}

export default defineConfig({
  compilation: {
    input: {
      index: './src/index.html'
    },
    output: {
      path: 'build',
      publicPath: '/',
      targetEnv: 'browser'
    }
  },
  plugins: [
    '@farmfe/plugin-react',
  ]
});

For configuration file above, we use input, output and plugins, which is the most basic configuration in Farm.

input: Configure the entry point. Farm will compile and build a module graph from the entries.
output: Confiture the output dir, file name and so on. For full options, see compilation.output.
plugins: Configure farm plugins, all extended abilities like React, Vue SFC are supported by plugins. Here we use a Rust Plugin(@farmfe/plugin-react) to support compiling React jsx.

Check config reference for more options.

note

In above example, we config input as index: './src/index.html', if we do not configure input, it's default to index: './index.html'. And we can configure multiple entries in input, see Multi Page App for details

Create A Entry Html and Js

Create 2 files src/index.html and src/index.tsx under project root:

.
├── farm.config.ts
├── package.json
├── pnpm-lock.yaml
└── src
    ├── index.html
    └── index.tsx

Content of src/index.html is:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Document</title>
</head>
<body>
  <div id="root"></div>
  <!-- we must use script to make ./index.tsx as a dependency -->
  <script src="./index.tsx"></script>
</body>
</html>

note

Note that we must add at least one <script> to refer to a script module.

Content of src/index.tsx is:

src/index.tsx
import React from 'react';
import { createRoot } from 'react-dom/client';

const container = document.querySelector('#root');
const root = createRoot(container);

root.render(<div>A React Page compiled by Farm</div>);

Start Your Farm Project!

Now every thing is ready, add a start script to your package.json:

package.json
{
  "name": "1-create-a-project",
  "version": "1.0.0",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "farm start"
  },
  // ... ignore other fields 
}

then run npm start, if farm output following messages, means your project are launched successfully:

$ npm start

> 1-create-a-project@1.0.0 start
> farm start

[ Farm ] Using config file at /home/tutorials/1-create-a-project/farm.config.ts

 ϟ  Farm  v0.16.0
 ✓  Ready in 20ms ⚡️ FULL EXTREME ! 

[ Farm ] > Local:   http://localhost:9000/
[ Farm ] > Network: http://192.168.1.3:9000/

Open http://localhost:9000 in browser.

Create A Project

Create A Package​

Install Dependencies​

Create Farm Config File​

Create A Entry Html and Js​

Start Your Farm Project!​

Create A Package

Install Dependencies

Create Farm Config File

Create A Entry Html and Js

Start Your Farm Project!