Skip to content

Latest commit

 

History

History
160 lines (137 loc) · 5.6 KB

README.md

File metadata and controls

160 lines (137 loc) · 5.6 KB
Raw

1. 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:

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:

{
  "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

> [email protected] start
> farm start

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

   ╭──────────────────────────────────────────────────╮
   │                                                  │
   │              _____ _    ____  __  __             │
   │             |  ___/ \  |  _ \|  \/  |            │
   │             | |_ / _ \ | |_) | |\/| |            │
   │             |  _/ ___ \|  _ <| |  | |            │
   │             |_|/_/   \_\_| \_\_|  |_|            │
   │                                                  │
   │                   Version 0.11.0                 │
   │                                                  │
   │     🔥 Ready on http://localhost:9000 in 61ms.   │
   │                                                  │
   │                                                  │
   ╰──────────────────────────────────────────────────╯

[ Farm ] HMR enabled, watching for file changes under /home/tutorials/1-create-a-project

Open http://localhost:9000 in browser.