AppFlowy/frontend/appflowy_web_app

AppFlowy Web Project

Welcome to the AppFlowy Web Project, a robust and versatile platform designed to bring the innovative features of AppFlowy to the web. This project uniquely supports running as a desktop application via Tauri, and offers web interfaces powered by WebAssembly (WASM). Dive into an exceptional development experience with high performance and extensive capabilities.

🐑 Features

• Cross-Platform Compatibility: Seamlessly run on desktop environments with Tauri, and on any web browser through WASM.
• High Performance: Leverage the speed and efficiency of WebAssembly for your web interfaces.
• Tauri Integration: Build lightweight, secure, and efficient desktop applications.
• Flexible Development: Utilize a wide range of AppFlowy's functionalities in your web or desktop projects.

🚀 Getting Started

🛠️ Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v14 or later)
• Rust (latest stable version)
• Tauri prerequisites for your operating system
• PNPM (8.5.0)

🏗️ Installation

Clone the Repository

git clone https://github.com/AppFlowy-IO/AppFlowy

🌐 Install the frontend dependencies:

 cd frontend/appflowy_web_app
 pnpm install

🖥️ Desktop Application (Tauri) (Optional)

Note

: if you want to run the web app in the browser, skip this step

• Follow the instructions here to install Tauri

Windows and Linux Prerequisites

Windows only

• Install the Duckscript CLI and vcpkg

    cargo install --force duckscript_cli
    vcpkg integrate install
  

Linux only

• Install the required dependencies

    sudo apt-get update
    sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.0-dev libappindicator3-dev librsvg2-dev patchelf
  

• Get error: failed to run custom build command for librocksdb-sys v6.11.4

    sudo apt install clang
  

Install Tauri Dependencies

• Install cargo-make

  cargo install --force cargo-make
  

• Install AppFlowy dev tools

  # install development tools
  # make sure you are in the root directory of the project
   cd frontend
   cargo make appflowy-tauri-deps-tools
  

• Build the service/dependency

   # make sure you are in the root directory of the project
   cd frontend/appflowy_web_app
   mkdir dist
   cd src-tauri
   cargo build
  

🚀 Running the Application

🌐 Web Application

• Run the web application

  pnpm run dev
  

• Open your browser and navigate to http://localhost:3000, You can now interact with the AppFlowy web application

🖥️ Desktop Application (Tauri)

Ensure close web application before running the desktop application

• Run the desktop application

  pnpm run tauri:dev
  

• The AppFlowy desktop application will open, and you can interact with it

🛠️ Development

How to add or modify i18n keys

• Modify the i18n files in frontend/resources/translations/en.json to add or modify i18n keys

• Run the following command to update the i18n keys in the application

  pnpm run sync:i18n
  

How to modify the theme

Don't modify the theme file in frontend/appflowy_web_app/src/styles/variables directly)

• Modify the theme file in frontend/appflowy_web_app/style-dictionary/tokens/base.json( or dark.json or light.json) to add or modify theme keys

• Run the following command to update the theme in the application

  pnpm run css:variables
  

How to add or modify the environment variables

• Modify the environment file in frontend/appflowy_web_app/.env to add or modify environment variables

How to create symlink for the @appflowyinc/client-api-wasm in local development

• Run the following command to create a symlink for the @appflowyinc/client-api-wasm

    # ensure you are in the frontend/appflowy_web_app directory
  
    pnpm run link:client-api $source_path $target_path
  
    # Example
    # pnpm run link:client-api ../../../AppFlowy-Cloud/libs/client-api-wasm/pkg ./node_modules/@appflowyinc/client-api-wasm
  

📝 About the Project

📁 Directory Structure

• frontend/appflowy_web_app: Contains the web application source code
• frontend/appflowy_web_app/src: Contains the app entry point and the source code
• frontend/appflowy_web_app/src/components: Contains the react components
• frontend/appflowy_web_app/src/styles: Contains the styles for the application
• frontend/appflowy_web_app/src/utils: Contains the utility functions
• frontend/appflowy_web_app/src/i18n: Contains the i18n files
• frontend/appflowy_web_app/src/assets: Contains the assets for the application
• frontend/appflowy_web_app/src/store: Contains the redux store
• frontend/appflowy_web_app/src/@types: Contains the typescript types
• frontend/appflowy_web_app/src/applications/services: Contains the services for the application. In vite.config.ts, we have defined the alias for the services directory for different environments(Tauri/Web)

    resolve: {
      alias: [
        // ...
        {
          find: '$client-services',
          replacement: !!process.env.TAURI_PLATFORM
            ? `${__dirname}/src/application/services/tauri-services`
            : `${__dirname}/src/application/services/js-services`,
        },
      ]
    }
  

📦 Deployment

Use the AppFlowy CI/CD pipeline to deploy the application to the test and production environments.

• Push the changes to the main branch
• Deploy Test Environment
  • Automatically, the test environment will be deployed if merged to the main branch or build/test branch
• Deploy Production Environment
  • Navigate to the Actions tab
  • Click on the workflow and select the Run workflow
  • Enter the options
  • Click on the Run workflow button

📦 Deployment (Self-Hosted EC2)

Pre-requisites

Please ensure you have learned about:

• Deploy Web application on AWS Cloud using EC2 Instance
• How to Install and Use Rsync Command
• How to Use ssh-keygen to Generate a New SSH Key?
• Linux post-installation steps for Docker Engine
• Configuring HTTPS servers

And then follow the steps below:

1. Ensure you have the following installed on your server:

   • Docker: Install Docker
   • Rsync: Install Rsync

2. Create a new user for deploy, and generate an SSH key for the user

   sudo adduser appflowy(or any name)
   sudo su - appflowy
   mkdir ~/.ssh
   chmod 700 ~/.ssh
   ssh-keygen -t rsa
   chmod 600 ~/.ssh/authorized_keys
   # add the user to the docker group, to run docker commands without sudo
   sudo usermod -aG docker ${USER}
   

   • visit the ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub to get the private and public key respectively
   • add the public key to the ~/.ssh/authorized_keys file
   • ensure the private key is kept safe
   • exit and login back to the server with the new user: ssh -i your-existing-key.pem ec2-user@your-instance-public-dns

3. Clone the AppFlowy repository

4. Set the following secrets in your repository, have to know Using secrets in GitHub Actions

Note: Test Environment: prefix the secret with WEB_TEST_ and Production Environment: prefix the secret with WEB_

for example, WEB_TEST_SSH_PRIVATE_KEY and WEB_SSH_PRIVATE_KEY

• SSH_PRIVATE_KEY: The private key generated in step 2: cat ~/.ssh/id_rsa
• REMOTE_HOST: The host of the server: your-instance-public-dns or your-instance-ip
• REMOTE_USER: The user created in step 2: appflowy
• SSL_CERTIFICATE: The SSL certificate for the server - Configuring HTTPS servers
• SSL_CERTIFICATE_KEY: The SSL certificate key for the server - Configuring HTTPS servers

5. Run the deployment workflow to deploy the application(production or test environment)

Note: the test server will automatically deploy if merged to the main branch or build/test branch

🧪 Testing

We use Cypress for end-to-end testing and component testing - Cypress

🧪 End-to-End Testing

to be continued

🧪 Component Testing

Run the following command to run the component tests

pnpm run test:components