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 start

This command starts the app in dev mode and opens it automatically, with the Chromium developer tools opened by default. Studio uses Electron Forge for running the app in dev mode, building, and packaging.

As with any Electron app, the code is split into two processes:

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

Running the CLI

The CLI is built separately from the Electron app. There are two commands to be aware of:

npm run cli:build runs a one-time build.
npm run cli:watch watches the source files and rebuilds automatically.

Both commands output a dist/cli/main.js file. To test the newly built CLI code, run the following command:

node dist/cli/main.js

Project Structure

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

Global Directories

Directory	Description
`cli/`	Root directory for CLI code
`common/`	Shared code between CLI and Studio (constants, types, utility functions, etc)
`src/`	Root directory for Studio code
`src/components/`	Reusable UI components used across the application
`src/hooks/`	Global React hooks
`src/lib/`	Utility functions and helper libraries
`src/modules/`	Feature-specific code
`src/stores/`	Global state management (Redux stores)
`src/api/`	API interfaces and implementations

Important Entry Points

File	Description
`cli/index.ts`	The entry point for the CLI bundle
`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. You can also use the React Developer Tools and Redux DevTools to debug the renderer process.

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

npm start -- --inspect-brk --sourcemap

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. While official packages are not yet available, you can build Studio from source:

npm install
npm run package

After building, the executable will be located at out/Studio-linux-x64/studio.

Important considerations:

The auto-update feature is not currently supported on Linux builds.
For Wayland systems, you may need to use additional flags when running the application.
Some features may not work as expected due to platform-specific implementations.

For detailed instructions including how to create a desktop launcher, handle Wayland compatibility, and troubleshoot common issues, see the Linux Guide.

Localization

See Localization documentation.

Versioning and Updates

See Versioning and Updates documentation.

Design Docs

Custom Domains and SSL
What's New modal
Sync

티스토리 수익 글 보기

티스토리 수익 글 보기

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!