> ## Documentation Index
> Fetch the complete documentation index at: https://vuemail.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Codebase overview

> An overview of the Vuemail codebase

We've created this guide to help new contributors understand and navigate the Vuemail codebase.

## Top-level directories

After cloning the [Vuemail repository](https://github.com/psycarlo/vuemail) you will see a few root-level directories. Here's a brief overview of each:

<table>
  <thead>
    <tr>
      <th>Directory</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        [apps](https://github.com/psycarlo/vuemail/tree/main/apps)
      </td>

      <td>
        Here you can find all of the apps related to our online presence, like:

        * this documentation (under [apps/docs](https://github.com/psycarlo/vuemail/tree/main/apps/docs)),
        * the demo emails we have on [demo.vuemail.dev](https://demo.vuemail.dev/preview/Community/notifications/vercel-invite-user)
          (under [apps/demo](https://github.com/psycarlo/vuemail/tree/main/apps/demo))
        * the Nuxt app we have for our landing page on [vuemail.dev](https://vuemail.dev) (under [apps/web](https://github.com/psycarlo/vuemail/tree/main/apps/web))
      </td>
    </tr>

    <tr>
      <td>
        [benchmarks](https://github.com/psycarlo/vuemail/tree/main/benchmarks)
      </td>

      <td>
        We make benchmarks from version-to-version to demonstrate data-observable performance gains with metrics like *p99 and p75*.

        For example, see the [Tailwind benchmark](https://github.com/psycarlo/vuemail/tree/main/benchmarks/tailwind), which measures the cost of rendering an email with the `Tailwind` component.
      </td>
    </tr>

    <tr>
      <td>
        [packages](https://github.com/psycarlo/vuemail/tree/main/packages)
      </td>

      <td>
        Most contributions will be made to the packages in this directory.

        This directory contains all our published [NPM](https://www.npmjs.com/) packages: the components,
        the CLI, the render utility, the preview app, the editor and the Nuxt module, alongside shared configuration.
      </td>
    </tr>
  </tbody>
</table>

> [!NOTE]
>
> Feel free to [open a discussion](https://github.com/psycarlo/vuemail/discussions) if you have suggestions on how to better structure these packages to make them more manageable and approachable.

## Multiple packages

The Vuemail repository is a [pnpm monorepo](https://pnpm.io/workspaces), which means it contains
multiple packages.

Because we use pnpm, you will need to use [pnpm](https://pnpm.io/) to install and run each package. If you do not have pnpm installed, follow the [pnpm installation guide](https://pnpm.io/installation):

```bash theme={null}
npm install -g pnpm
```

Currently, we have the following packages:

* [@vuemaildev/vuemail](https://github.com/psycarlo/vuemail/tree/main/packages/vuemail)
  * The package for our [email CLI](https://vuemail.dev/docs/cli.md), and for all of our components
* [@vuemaildev/render](https://github.com/psycarlo/vuemail/tree/main/packages/render)
  * The [render](https://vuemail.dev/docs/utilities/render.md) utility. Can also be imported from `@vuemaildev/vuemail`.
* [@vuemaildev/ui](https://github.com/psycarlo/vuemail/tree/main/packages/ui)
  * The preview app the CLI runs
* [@vuemaildev/editor](https://github.com/psycarlo/vuemail/tree/main/packages/editor)
  * The embeddable [visual editor](https://vuemail.dev/docs/editor/overview.md) for composing emails
* [@vuemaildev/nuxt](https://github.com/psycarlo/vuemail/tree/main/packages/nuxt)
  * The [Nuxt module](https://vuemail.dev/docs/getting-started/nuxt.md) that lets server routes render emails
* [create-vuemail](https://github.com/psycarlo/vuemail/tree/main/packages/create-vuemail)
  * Used for our [automatic setup](https://vuemail.dev/docs/getting-started/automatic-setup.md)

### Turborepo

We encourage using [turborepo](https://turbo.build/repo) to manage the packages.

It's often helpful to [install Turborepo globally](https://turbo.build/repo/docs/installing) to make it easier to run commands in any of the repositories. With a global installation, running `turbo build` in any of the packages will build both the package
you are on as well as the dependent packages. The global installation handles [version mismatching as well](https://turbo.build/repo/docs/installing#install-per-repository).

### The Vuemail CLI

The CLI is built using [commander](https://www.npmjs.com/package/commander), a CLI builder for node. It handles
parsing of command line arguments and ensuring that the syntax for the command is as expected.

The `dev`, `build`, `start` and `export` commands all depend on the user first installing `@vuemaildev/ui`,
in the same version as `@vuemaildev/vuemail`. The CLI loads it from the user's project, and when it's missing or its
version doesn't match, it asks to install it, using [nypm](https://www.npmjs.com/package/nypm) to add it
with the user's package manager.

### The Preview Server

The Preview Server, `@vuemaildev/ui`, has two sides:

* `src/node` is the server the CLI starts. It compiles the user's emails with [Vite](https://vite.dev) and
  `@vitejs/plugin-vue`, loading them with Vite's server-side module loader, and renders them with the
  [render](https://vuemail.dev/docs/utilities/render.md) utility from the user's own `@vuemaildev/vuemail`. Vite's file watcher detects changes to
  the files the emails depend on, which the server sends to the browser as server-sent events.
* `src/client` is the preview app itself, a Vue 3 single page app built with Vite, [vue-router](https://router.vuejs.org),
  [reka-ui](https://reka-ui.com) and Tailwind CSS 4.

As changes are sent to the preview app, the preview updates automatically. `email build` renders every
email ahead of time instead, into a static website.

## Testing

For testing, we use [vitest](https://vitest.dev/). We prefer to define globals, and run tests under the `happy-dom`
environment for the code that runs in the browser, like the preview app and the editor, and under `node` for the rest.

We do not strictly enforce testing coverage, but encourage it.

For help testing, see our [Development workflow guide](https://vuemail.dev/docs/contributing/development-workflow/2-running-tests.md).

> [!NOTE]
>
> The tests of `@vuemaildev/nuxt` build and start real Nuxt apps, so they take longer than the others.

## Linting

We use [biomejs](https://biomejs.dev/) for linting and formatting. Both the linting and formatting are ensured by our GitHub CI so make sure you lint and format your code (`pnpm lint:fix`) before opening a PR or asking for a review on it.

For help linting and formatting, see our [Development workflow guide on linting](https://vuemail.dev/docs/contributing/development-workflow/3-linting.md).

## Building

We use [tsdown](https://tsdown.dev) to build the packages. The preview app of `@vuemaildev/ui` is built with
[Vite](https://vite.dev). For help building packages, see our [Development workflow guide](https://vuemail.dev/docs/contributing/development-workflow/4-building.md).

> [!NOTE]
>
> Building each package runs `tsdown` with the settings in its `tsdown.config.ts`. `@vuemaildev/vuemail` and `@vuemaildev/render` are built as both ESM and CJS,
> along with the type definitions exported from the entry point, `src/index.ts`, without bundling `vue`, which can cause issues.

### Why build before publishing?

We build the packages before publishing for a few reasons:

1. All the exported types can be imported from the same place the JavaScript is imported
2. We have proper [CommonJS](https://nodejs.org/docs/latest/api/modules.html#modules-commonjs-modules)
   and [ES Modules](https://nodejs.org/api/esm.html#modules-ecmascript-modules) support
3. Code that isn't exported is not published or downloaded


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.