AGENTS.md · OutlineFoundation/outline-apps

Sections

1. Repository Structure
2. The npm run action Command
3. Code Style
4. Requirements
5. Common Concepts

First lines (shown under the repo's Apache-2.0 license)

# Welcome to the Outline Monorepo!

This document provides a guide for AI and human agents working with the Outline codebase.

## Repository Structure

The Outline monorepo is organized into three main components:

*   `/client`: The Outline Client application, available on all major platforms. See [`client/AGENTS.md`](client/AGENTS.md).
*   `/server_manager`: A graphical application to create and manage Outline Servers. See [`server_manager/AGENTS.md`](server_manager/AGENTS.md).
*   `/infrastructure`: The build system and shared TypeScript utilities. See [`infrastructure/AGENTS.md`](infrastructure/AGENTS.md).

## The `npm run action` Command

The primary entry point for all development tasks is `npm run action <path>`, which resolves to `.action.sh` or `.action.mjs` files in the repo. Run `npm run action list` to see all available actions. Pass flags after `--`:

```sh
npm run action client/src/cordova/setup macos -- --buildMode=release
```

### Common Actions

*   `npm run action list`: Lists all available actions.
*   `npm run action client/web/start`: Starts a dev server for the shared web UI.
*   `npm run action server_manager/www/start`: Starts a dev server for the Manager UI.
*   `npm run action <component>/test`: Runs tests (e.g. `npm run action client/web/test`).
*   `npm run action <component>/build`: Builds a component (e.g. `npm run action client/electron/build linux -- --arch=x64`).

### Other useful commands

*   `npm run reset`: Clean and reinstall all dependencies (fixes most build issues).
*   `npm run storybook`: Launch the Storybook UI component explorer.
*   `npm run lint:gts`: Lint TypeScript (pass filepaths on macOS; works on all files on Linux).

## Code Style

*   **TypeScript**: Follows [Google's TypeScript style](https://google.github.io/styleguide/tsguide.html), enforced by [`gts`](https://github.com/google/gts). Run `npm run lint:gts` to check and `npm run format:all` to auto-fix (Linux only for whole codebase; pass specific filepaths on macOS).
*   **Go**: Follows standard Go style. Use `gofmt` and `go vet`.

## Requirements

| Component | Version |
|-----------|---------|
| Node.js   | 22 — run `nvm use` if you have nvm |
| Go        | 1.22+   |

Platform-specific requirements (Android SDK, Xcode, zig for cross-compilation) are documented in the relevant subdirectory AGENTS.md files.

## Common Concepts

*   **Access Keys**: Credentials used by Outline clients to connect to an Outline server. Generated by the Outline Manager.
*   **Shadowbox**: The core proxy component of Outline, responsible for handling network traffic.
*   **Outline Client**: The end-user application for connecting to the internet through an Outline server.
*   **Server Manager**: The application used to create and manage Outline servers on cloud providers.
*   **Electron**: Framework used to build the desktop versions of the Outline Client and Server Manager.
*   **Cordova**: Framework used to build the mobile (iOS/Android) and macOS versions of the Outline Client.
*   **Lit**: The UI framework for web components. All new components use Lit. The client has fully migrated; the server_manager still has legacy Polymer components in its app shell being migrated.
*   **OutlineAction**: A custom build script (`.action.sh` or `.action.mjs`) that defines a task runnable via `npm run action`.