163 lines
5.1 KiB
Markdown
163 lines
5.1 KiB
Markdown
<div align="center">
|
|
<div align="center">
|
|
<h1>AppFlowy Web</h1>
|
|
</div>
|
|
<img src="https://img.shields.io/badge/React-v18.2.0-blue"/>
|
|
<img src="https://img.shields.io/badge/TypeScript-v4.9.5-blue"/>
|
|
<img src="https://img.shields.io/badge/Nginx-v1.21.6-brightgreen"/>
|
|
<img src="https://img.shields.io/badge/Bun-latest-black"/>
|
|
<img src="https://img.shields.io/badge/Docker-v20.10.12-blue"/>
|
|
</div>
|
|
|
|
## 🌟 Introduction
|
|
|
|
Welcome to the AppFlowy Web project! This project aims to bring the powerful features of AppFlowy to the web. Whether
|
|
you're a developer looking to contribute or a user eager to try out the latest features, this guide will help you get
|
|
started.
|
|
|
|
AppFlowy Web is built with the following technologies:
|
|
|
|
- **React**: A JavaScript library for building user interfaces.
|
|
- **TypeScript**: A typed superset of JavaScript that compiles to plain JavaScript.
|
|
- **Bun**: A fast all-in-one JavaScript runtime.
|
|
- **Nginx**: A high-performance web server.
|
|
- **Docker**: A platform to develop, ship, and run applications in containers.
|
|
|
|
### Resource Sharing
|
|
|
|
To maintain consistency across different platforms, the Web project shares i18n translation files and Icons with the
|
|
Flutter project. This ensures a unified user experience and reduces duplication of effort in maintaining these
|
|
resources.
|
|
|
|
- **i18n Translation Files**: The translation files are shared to provide a consistent localization experience across
|
|
both Web and Flutter applications. The path to the translation files is `frontend/resources/translations/`.
|
|
|
|
> The translation files are stored in JSON format and contain translations for different languages. The files are
|
|
named according to the language code (e.g., `en.json` for English, `es.json` for Spanish, etc.).
|
|
|
|
- **Icons**: The icon set used in the Web project is the same as the one used in the Flutter project, ensuring visual
|
|
consistency. The icons are stored in the `frontend/resources/flowy_icons/` directory.
|
|
|
|
Let's dive in and get the project up and running! 🚀
|
|
|
|
## 🛠 Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
Before you begin, make sure you have the following installed on your system:
|
|
|
|
- [Node.js](https://nodejs.org/) (v18.6.0) 🌳
|
|
- [pnpm](https://pnpm.io/) (package manager) 📦
|
|
- [Jest](https://jestjs.io/) (testing framework) 🃏
|
|
- [Cypress](https://www.cypress.io/) (end-to-end testing) 🧪
|
|
|
|
### Clone the Repository
|
|
|
|
First, clone the repository to your local machine:
|
|
|
|
```bash
|
|
git clone https://github.com/AppFlowy-IO/AppFlowy-Web.git
|
|
```
|
|
|
|
### Install Dependencies
|
|
|
|
Install the required dependencies using pnpm:
|
|
|
|
```bash
|
|
## ensure you have pnpm installed, if not run the following command
|
|
# npm install -g pnpm@8.5.0
|
|
|
|
pnpm install
|
|
```
|
|
|
|
### Configure Environment Variables
|
|
|
|
Create a `.env` file in the root of the project and add the following environment variables:
|
|
|
|
```bash
|
|
AF_BASE_URL=http://localhost:8080
|
|
AF_GOTRUE_URL=http://localhost:9999
|
|
AF_WS_URL=ws://localhost:8080/ws/v1
|
|
```
|
|
|
|
### Start the Development Server
|
|
|
|
To start the development server, run the following command:
|
|
|
|
```bash
|
|
pnpm run dev
|
|
```
|
|
|
|
### 🚀 Building for Production(Optional)
|
|
|
|
if you want to run the production build, use the following commands
|
|
|
|
```bash
|
|
pnpm run build
|
|
pnpm run start
|
|
```
|
|
|
|
This will start the application in development mode. Open http://localhost:3000 to view it in the browser.
|
|
|
|
## 🧪 Running Tests
|
|
|
|
### Unit Tests
|
|
|
|
We use **Jest** for running unit tests. To run the tests, use the following command:
|
|
|
|
```bash
|
|
pnpm run test:unit
|
|
```
|
|
|
|
This will execute all the unit tests in the project and provide a summary of the results. ✅
|
|
|
|
### Components Tests
|
|
|
|
We use **Cypress** for end-to-end testing. To run the Cypress tests, use the following command:
|
|
|
|
```bash
|
|
pnpm run cypress:open
|
|
```
|
|
|
|
This will open the Cypress Test Runner where you can run your end-to-end tests. 🧪
|
|
|
|
Alternatively, to run Cypress tests in the headless mode, use:
|
|
|
|
```bash
|
|
pnpm run test:components
|
|
```
|
|
|
|
Both commands will provide detailed test results and generate a code coverage report.
|
|
|
|
## 🔄 Development Workflow
|
|
|
|
### Linting
|
|
|
|
To maintain code quality, we use **ESLint**. To run the linter and fix any linting errors, use the following command:
|
|
|
|
```bash
|
|
pnpm run lint
|
|
```
|
|
|
|
## 🚀 Production Deployment
|
|
|
|
Our production deployment process is automated using GitHub Actions. The process involves:
|
|
|
|
1. **Setting up an AWS EC2 instance**: We use an EC2 instance to host the application.
|
|
2. **Installing Docker and Docker Compose**: Docker is installed on the AWS instance.
|
|
3. **Configuring SSH Access**: SSH access is set up with a user and password.
|
|
4. **Preparing Project Configuration**: We configure `Dockerfile`, `nginx.conf`, and `server.cjs` in the web project.
|
|
5. **Using GitHub Actions**: We use the easingthemes/ssh-deploy@main action to deploy the project to the remote server.
|
|
|
|
The deployment steps include building the Docker image and running the Docker container with the necessary port
|
|
mappings:
|
|
|
|
```bash
|
|
docker build -t appflowy-web-app .
|
|
docker rm -f appflowy-web-app || true
|
|
docker run -d -p 80:80 -p 443:443 --name appflowy-web-app appflowy-web-app
|
|
```
|
|
|
|
The Web server runs on Bun. For more details about Bun, please refer to the [Bun documentation](https://bun.sh/).
|
|
|