Skip to content

Latest commit

 

History

History
195 lines (131 loc) · 6.92 KB

code-contributions.md

File metadata and controls

195 lines (131 loc) · 6.92 KB

Code Contributions

Development

Required Dependencies

Before you can build and run the app, you need to install the following dependencies:

  • Node.js - required JavaScript runtime environment.
  • Python - required for building native dependencies.
  • setuptools - required for building native dependencies.

Many project contributors rely upon nvm and Homebrew to manage Node.js and Python installations respectively.

If you manage packages with Homebrew you can do the following:

brew install python3 python-setuptools

nvm commands referenced in the remaining documentation operate under the assumption that installed Node.js versions are managed with nvm. To use the correct Node.js version and install the project dependencies, run the following commands:

nvm use
npm install

Running the App

Once all required dependencies are installed, you can run the app with the following command:

npm install
npm start

The app automatically launches with the Chromium developer tools opened by default. The code is split into two processes:

  1. Renderer Process (reloads automatically):

    • All React components and UI code in src/components/, src/modules/*/components/
    • Hooks, stores, and utilities used by the UI (src/hooks/, src/stores/, etc.)
    • Any code that runs in the browser window context

  2. Main Process (requires restart):

    • IPC handlers in src/ipc-handlers.ts
    • Electron main process code in src/index.ts
    • Node.js operations like file system access
    • PHP server management code

When editing main process code, you can either:

  • Restart the app manually, or
  • Type rs in the terminal where you ran npm start to restart the server

A good rule of thumb: if the code interacts with the operating system, file system, or PHP server, it's likely main process code and will need a restart to see changes.

Tip

If you encounter Error: Cannot find module 'appdmg' error, ensure that python-setuptools are installed in your environment according to the previous steps.

Project Structure

The project follows a modular architecture with both global and feature-specific code organization:

Global Directories

  • src/components/ - Reusable UI components used across the application
  • src/hooks/ - Global React hooks
  • src/lib/ - Utility functions and helper libraries
  • src/stores/ - Global state management (Redux stores)
  • src/api/ - API interfaces and implementations

Important Entry Points

  • scripts/ - Scripts for building and testing the app
  • src/index.ts - The entry point for the main process
  • src/renderer.ts - The entry point for the "renderer," the code running in the Chromium window
  • vendor/wp-now - The modified wp-now source code

Feature Modules

Feature-specific code is organized in the src/modules/ directory. Each module follows a consistent internal structure:

src/modules/
  ├── preview-site/          # Preview sites feature
  │   ├── components/        # Feature-specific components
  │   ├── hooks/             # Feature-specific hooks
  │   └── lib/               # Feature-specific utilities
  │
  ├── ai-assistant/          # AI Assistant feature
  │   └── ...
  │
  └── sidebar/               # Sites sidebar feature
      └── ...

Each feature module should be self-contained and include its own components, hooks, and utilities. This organization helps maintain separation of concerns and makes the codebase more maintainable.

Code Formatting

Code formatting is set up to make merging pull requests easier. It uses the same Prettier/ESLint mechanism as Calypso, the code powering the WordPress.com dashboard. See JavaScript Coding Guidelines for guidance on setting up your editor for code formatting.

CLI Development

The CLI relies upon a separate instance of the app to run. When developing the CLI, the CLI can be invoked with the following steps:

  • Run npm start to launch the first instance of the app.
  • Within the forge.config.ts file, change the WebpackPlugin ports used for the second instance:
    • Set the development port to 3457.
    • Add a loggerPort property set to 9001.
  • Run npm start -- -- --cli"=<CLI-COMMAND>" in separate terminal session.

Testing

Unit Tests

Automated unit tests can be run with the following command:

npm run test

Or to run tests in "watch" mode:

npm run test:watch

End-to-End Tests

Automated end-to-end (E2E) tests are also available. To run them, clean the out/ directory and build the fresh app binary:

npm run make

Then run tests:

npm run e2e

Debugging

The renderer process can be debugged using the Chromium developer tools. To open the developer tools, press Cmd+Option+I on Mac or Ctrl+Shift+I on Windows.

The React tree in the renderer process can be debugged with the standalone React Developer Tools. To do this, start the the React Developer Tools and then start the app with the REACT_DEV_TOOLS=true flag set.

First, install and run the React Developer Tools:

npx react-devtools

Then start the app with the REACT_DEV_TOOLS=true flag:

REACT_DEV_TOOLS=true npm start

The main process can be debugged using the Node.js inspector. To do this, run the app with the --inspect-brk-electron flag:

npm start -- --inspect-brk-electron

Then open chrome://inspect in a Chromium-based browser and click "inspect" next to the process you want to debug.

Building Installers

Once all required dependencies are installed, you can build installers for the app. Installers can currently be built on Mac (Intel or Apple Silicon), Windows, and experimentally for Linux using the following commands:

npm install
npm run make

After the build process completes, you can find the executables in the out/ directory.

Linux

Linux support is currently in an experimental phase and comes with certain limitations:

  • For systems using Wayland, you may need to set the --enable-features=UseOzonePlatform --ozone-platform=wayland flag when running the application.
  • Some features may not work as expected on Linux due to platform-specific implementations.
  • The auto-update feature is not currently supported on Linux builds.
  • While these instructions should work for most Linux distributions, you may need to adjust them based on your specific setup or distribution.

Localization

See Localization documentation.

Versioning and Updates

See Versioning and Updates documentation.