# plasmohq/plasmo architecture

> Architecture diagram of the GitHub repository plasmohq/plasmo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/plasmohq/plasmo
- Repository: https://github.com/plasmohq/plasmo

## Overview

##### Project’s Type and Purpose
- This repository is organized as a monorepo that appears to provide a tool (Plasmo) for developing browser extensions. It encompasses multiple subprojects such as APIs for messaging and persistence, a rich CLI with scaffolding and feature management (in cli/plasmo and cli/create-plasmo), a comprehensive suite of core libraries for bundling, packaging, and asset transformation (found under core/), and various shared packages (under packages/) to support extension development.
- The primary goal is to offer a development environment that not only scaffolds and builds extensions but also handles communication, bundling, and deployment using custom-build pipelines (with parts that interface with bundlers, transformers, and resolvers).

##### File Structure and Extract the Main Components
- API Modules (located in api/):
– Contains specialized directories such as “messaging”, “persistent”, “selector”, and “storage.”
– These are likely responsible for different aspects of inter-process or in-extension communication and persistent state management.

- CLI Tools (located in cli/):
– Two main CLI components: one for “create-plasmo” (scaffolding a new project) and one for “plasmo”, which contains an extensive set of commands (build, dev, help, init, version, etc.).
– Includes features such as internationalization (i18n), project creation from existing manifests, and template management.

- Core Libraries (located in core/):
– Contains various “parcel-*” subcomponents that handle different phases of bundling, compression, resolving dependencies, optimization (e.g., parcel-bundler, parcel-transformer-*).
– They are modular to support different aspects: bundling code, injecting environment variables (inject-env), inline CSS transformation, and even support for multiple view-layer frameworks (react, vue, svelte, etc.).

- Shared Packages (located in packages/):
– Packages that provide shared configurations, constants, framework shared utilities, and even initialization templates.
– These will interconnect with both the CLI and core processes.

- Additional Project Infrastructure:
– The .github folder, configuration files (like pnpm-lock.yaml, turbo.json, tsconfig, etc.), and scripts provide continuous integration, code style enforcement, and workspace management.

- At a high level, separate the architecture into these layers/components:
- Frontend/Extension Side (APIs and messaging layers): Represent the messaging, persistent state, and selector APIs that serve as the extension’s runtime and communication mechanism.
- CLI Layer: A console-based interface that users invoke (through “plasmo” and “create-plasmo”) to scaffold, build, or run their projects. This layer also manages extending support via internationalization and feature toggles.
- Core Engine Layer: The series of “core/parcel-*” modules forming the backbone for code bundling, optimization, and deployment. These parts are fundamental in translating source code into deployable assets.
- Support/Shared Modules: The various packages (e.g., framework-shared, init, permission-ui) which encapsulate auxiliary tools, templating systems, and shared constants.

- Relationships and Data Flow:
- The CLI layer directly interacts with the Core Engine to trigger bundling, transformation, and packaging whenever commands such as “build” or “dev” are executed.
- The API modules serve as the communication bridge between different parts of the extension runtime (e.g., background scripts, content scripts) and interface with the runtime provided by the Core Engine.
- Shared packages furnish common configurations and utilities that are consumed by both the CLI tools and the core modules.
- External services such as GitHub actions (in the .github folder) manage CI/CD integration, ensuring that tests and code quality checks are enforced.

##### Architectural Patterns and Design Principles
- Modular Design & Separation of Concerns: The repository clearly isolates scaffolding (CLI), runtime APIs (api/*), and build logic (core/*), which makes it easier to extend or swap components.
- Plugin-like / Extendability: The structure under “core” with various “parcel-transformer-” modules suggests a pluggable architecture for different file types or framework-specific transformations.
- Workspace/Monorepo Structure: Using standardized tooling (pnpm, turbo, etc.) to manage interdependent packages and ensure consistency across tools.

##### Final Advice
- Be detailed in capturing each module and their sub-components – for instance, break down the “core” folder into its multiple submodules (bundler, runtime, transformers, etc.) as this is key to understanding the build process.
- Do not shy away from decomposing components further if they represent significant responsibilities.
- The goal is to have an architectural “map” that anyone (especially a principal software engineer) can follow to both understand and extend the system.

## Diagram (Mermaid)

```mermaid
graph TD
    %% CLI Layer
    subgraph "CLI Layer"
        cliCreate["CLI: Create Plasmo"]:::cli
        cliCore["CLI: Plasmo"]:::cli
    end

    %% Core Engine Layer
    subgraph "Core Engine Layer"
        bundler["Parcel Bundler"]:::core
        compressor["Parcel Compressor (UTF8)"]:::core
        config["Parcel Config"]:::core
        parcelCore["Parcel Core"]:::core
        namer["Parcel Namer Manifest"]:::core
        subgraph "Parcel Optimizers"
            optimizerEnc["Parcel Optimizer Encapsulate"]:::core
            optimizerES["Parcel Optimizer ES"]:::core
        end
        packager["Parcel Packager"]:::core
        subgraph "Parcel Resolvers"
            resolver["Parcel Resolver"]:::core
            resolverPost["Parcel Resolver Post"]:::core
        end
        runtime["Parcel Runtime"]:::core
        subgraph "Parcel Transformers"
            transformerInject["Parcel Transformer Inject Env"]:::core
            transformerInline["Parcel Transformer Inline CSS"]:::core
            transformerLab["Parcel Transformer Lab"]:::core
            transformerManifest["Parcel Transformer Manifest"]:::core
            transformerSvelte["Parcel Transformer Svelte"]:::core
            transformerVue["Parcel Transformer Vue"]:::core
        end
    end

    %% API Layer
    subgraph "API Layer"
        apiMessaging["API: Messaging"]:::api
        apiPersistent["API: Persistent"]:::api
        apiSelector["API: Selector"]:::api
        apiStorage["API: Storage"]:::api
    end

    %% Shared Packages and Infrastructure
    subgraph "Shared & Infrastructure"
        sharedPkg["Shared Packages"]:::shared
        projectInfra["Project Infrastructure"]:::infra
    end

    %% Connections

    %% CLI interactions
    cliCore -->|"build"| bundler
    cliCreate -->|"scaffold"| sharedPkg

    %% Core Engine flow
    bundler -->|"compress"| compressor
    compressor -->|"configure"| config
    config -->|"integrate"| parcelCore
    parcelCore -->|"naming"| namer
    namer -->|"optimize"| optimizerEnc
    optimizerEnc -->|"further-optimize"| optimizerES
    optimizerES --> packager
    packager -->|"resolve"| resolver
    resolver --> resolverPost
    resolverPost --> runtime

    %% Runtime to API communication
    runtime -->|"communicates"| apiMessaging
    apiMessaging -->|"syncs-with"| apiPersistent
    apiPersistent -->|"selects"| apiSelector
    apiSelector -->|"stores-to"| apiStorage

    %% Shared Packages support
    cliCore ---|"utilizes"| sharedPkg
    parcelCore ---|"uses"| sharedPkg
    projectInfra -->|"CI/CD"| sharedPkg
    cliCore -->|"init"| projectInfra

    %% Core Engine Transformers flow
    runtime -->|"transforms"| transformerInject
    transformerInject --> transformerInline
    transformerInline --> transformerLab
    transformerLab --> transformerManifest
    transformerManifest --> transformerSvelte
    transformerSvelte --> transformerVue

    %% Click Events
    click apiMessaging "https://github.com/plasmohq/plasmo/tree/main/api/messaging"
    click apiPersistent "https://github.com/plasmohq/plasmo/tree/main/api/persistent"
    click apiSelector "https://github.com/plasmohq/plasmo/tree/main/api/selector"
    click apiStorage "https://github.com/plasmohq/plasmo/tree/main/api/storage"
    click cliCreate "https://github.com/plasmohq/plasmo/tree/main/cli/create-plasmo"
    click cliCore "https://github.com/plasmohq/plasmo/tree/main/cli/plasmo"
    click bundler "https://github.com/plasmohq/plasmo/tree/main/core/parcel-bundler"
    click compressor "https://github.com/plasmohq/plasmo/tree/main/core/parcel-compressor-utf8"
    click config "https://github.com/plasmohq/plasmo/tree/main/core/parcel-config"
    click parcelCore "https://github.com/plasmohq/plasmo/tree/main/core/parcel-core"
    click namer "https://github.com/plasmohq/plasmo/tree/main/core/parcel-namer-manifest"
    click optimizerEnc "https://github.com/plasmohq/plasmo/tree/main/core/parcel-optimizer-encapsulate"
    click optimizerES "https://github.com/plasmohq/plasmo/tree/main/core/parcel-optimizer-es"
    click packager "https://github.com/plasmohq/plasmo/tree/main/core/parcel-packager"
    click resolver "https://github.com/plasmohq/plasmo/tree/main/core/parcel-resolver"
    click resolverPost "https://github.com/plasmohq/plasmo/tree/main/core/parcel-resolver-post"
    click runtime "https://github.com/plasmohq/plasmo/tree/main/core/parcel-runtime"
    click transformerInject "https://github.com/plasmohq/plasmo/tree/main/core/parcel-transformer-inject-env"
    click transformerInline "https://github.com/plasmohq/plasmo/tree/main/core/parcel-transformer-inline-css"
    click transformerLab "https://github.com/plasmohq/plasmo/tree/main/core/parcel-transformer-lab"
    click transformerManifest "https://github.com/plasmohq/plasmo/tree/main/core/parcel-transformer-manifest"
    click transformerSvelte "https://github.com/plasmohq/plasmo/tree/main/core/parcel-transformer-svelte"
    click transformerVue "https://github.com/plasmohq/plasmo/tree/main/core/parcel-transformer-vue"
    click sharedPkg "https://github.com/plasmohq/plasmo/tree/main/packages"
    click projectInfra "https://github.com/plasmohq/plasmo/blob/main/.github"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef core fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef api fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef shared fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
