# remorses/unframer architecture

> Architecture diagram of the GitHub repository remorses/unframer, 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/remorses/unframer
- Repository: https://github.com/remorses/unframer

## Overview

##### Main components and their responsibilities
- CLI & Core Logic:
- The “unframer” CLI (see unframer/bin.js and src/cli.tsx) is the entry point that interacts with the Framer export component URLs (populated by a Framer plugin) and triggers the download, TypeScript type extraction, style generation, and bundling logic.
- It invokes internal modules (like those in unframer/src) to perform tasks such as fetching remote URLs, running esbuild for bundling, generating the “styles.css” with global Framer styles, and integrating npm dependency resolutions.
- Bundler and Type Generation:
- A module built on top of esbuild (see unframer/src/esbuild.ts) is responsible for bundling the external Framer component code.
- The type extraction part reads the “propertyControls” from each exported component to generate full TypeScript type definitions.
- Scripts & Utilities:
- Several scripts in /unframer/scripts (debugging, sourcemaps-exporter, version replace, etc.) support the overall build and export process.
- Utility functions in unframer/src/utils.ts and others manage common tasks.
- Framer Plugin Integration:
- The tool depends on data (URLs, export settings) pushed by the “React Export” Framer plugin. This component is not part of the codebase but acts as an external interface.
- Sample Framework Applications:
- The reactive demo apps (Astro, Next.js, Remix) included in the repository demonstrate how the exported components (and their CSS, props, responsive variants, dark mode settings, etc.) integrate into real-world projects.
- External Dependencies:
- The architecture draws on external libraries such as React 19, esbuild, and others that affect runtime behavior (e.g., handling React Strict Mode and SSR).

##### Relationships and interactions
- The CLI starts the process (using commands like “npx unframer {projectId} --outDir ./src/framer”) and triggers the internal pipeline.
- It issues HTTP HEAD requests (polling the Framer website for changes) to detect new exports.
- When a change is detected, the CLI downloads the component JavaScript modules and bundles them with esbuild.
- The bundler then resolves npm dependencies automatically (with options for external dependencies) and produces bundled JS files plus accompanying CSS (for global styles and fonts).
- Generated output (components with type definitions) can be integrated by downstream sample apps. These apps import the generated ‘styles.css’ and module exports (e.g., Menus, Logos) and implement responsive rendering, client-side navigation, localization, and dark mode.
- Directional data flow should be shown from user actions in Framer to component export, processing via the CLI, and finally consumption in one of the sample front-end apps.

##### Important architectural patterns and design principles
- Separation of concerns: The CLI is responsible for orchestration, while the bundler and type extractor handle their dedicated tasks.
- Modular design: The code is divided across logical directories (e.g., unframer/src for core functionality; scripts for auxiliary processes; separate sample apps for integration).
- Extensibility: The output supports a wide range of frameworks, and the architecture is built so that additional processing (such as more advanced dependency resolution or new export formats) can be added.
- Component reusability: The exported Framer components are designed to be framework-agnostic and integrate seamlessly into various React ecosystems.

##### Specific elements
- Clear labels:
- The “unframer CLI”.
- Core modules (“Fetcher”, “Bundler & Type Generator”, “Asset/Style Exporter”).
- Integration flow into sample front-end projects.
- Internal modules vs. external services (like Framer).
- Build-time processes (CLI, bundler) versus runtime components (exported React components in sample apps).
- Optional pathways like the “--watch” mode which continuously polls and triggers rebundling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External System
    ExternalFramer["Framer (React Export Plugin)"]:::external

    %% CLI Entry Point
    CLIEntry["unframer CLI Entry Point"]:::cli

    %% Supporting Scripts & Utilities
    subgraph "Supporting Scripts & Utilities"
        AuxScripts["Auxiliary Scripts"]:::utils
        Utils["Utility Functions"]:::utils
    end

    %% Component Export Pipeline
    subgraph "Component Export Pipeline"
        Fetcher["Fetcher & Exporter"]:::pipeline
        Bundler["Bundler & Type Generator"]:::pipeline
        CSSGen["Asset & Style Generator"]:::pipeline
    end

    %% Generated Output
    Generated["Generated Components/Styles"]:::result

    %% Sample Framework Applications
    subgraph "Sample Framework Applications"
        AstroApp["Astro Sample App"]:::app
        NextJsApp["Next.js Sample App"]:::app
        RemixApp["Remix Sample App"]:::app
    end

    %% Data Flow Connections
    ExternalFramer -->|"suppliesExportURLs"| CLIEntry
    CLIEntry -->|"initiatesProcess"| Fetcher
    Fetcher -->|"bundlesComponents"| Bundler
    Bundler -->|"generatesAssets"| CSSGen
    CSSGen -->|"outputsAssets"| Generated
    Generated -->|"importsComponents"| AstroApp
    Generated -->|"importsComponents"| NextJsApp
    Generated -->|"importsComponents"| RemixApp
    AuxScripts ---|"supportsBuild"| CLIEntry
    Utils ---|"supportsTasks"| CLIEntry

    %% Click Events for CLI Entry Point (two files)
    click CLIEntry "https://github.com/remorses/unframer/blob/main/unframer/bin.js"
    click CLIEntry "https://github.com/remorses/unframer/blob/main/unframer/src/cli.tsx"

    %% Click Events for Core Processing Modules
    click Fetcher "https://github.com/remorses/unframer/blob/main/unframer/src/exporter.ts"
    click Bundler "https://github.com/remorses/unframer/blob/main/unframer/src/esbuild.ts"
    click CSSGen "https://github.com/remorses/unframer/blob/main/unframer/src/css.ts"

    %% Click Events for Supporting Scripts & Utilities
    click AuxScripts "https://github.com/remorses/unframer/tree/main/unframer/scripts"
    click Utils "https://github.com/remorses/unframer/blob/main/unframer/src/utils.ts"

    %% Click Events for Sample Framework Applications
    click AstroApp "https://github.com/remorses/unframer/tree/main/astro-app"
    click NextJsApp "https://github.com/remorses/unframer/tree/main/nextjs-app"
    click RemixApp "https://github.com/remorses/unframer/tree/main/remix-app"

    %% Styles
    classDef external fill:#ffdead,stroke:#d2691e,stroke-width:2px;
    classDef cli fill:#a2d2ff,stroke:#023e8a,stroke-width:2px;
    classDef pipeline fill:#caf0f8,stroke:#0077b6,stroke-width:2px;
    classDef result fill:#d0f4de,stroke:#40916c,stroke-width:2px;
    classDef app fill:#caffbf,stroke:#2b9348,stroke-width:2px;
    classDef utils fill:#e0bbe4,stroke:#9d4edd,stroke-width:2px;
```
