VitePress

Appearance

Core Packages Overview ​

Our monorepo is organized into several types of packages, each with a specific role. Understanding these roles helps keep business logic, data modeling, frontend code, and assets cleanly separated and maintainable.

Core Business Logic ​

@mmv3/core ​

  • Purpose: The main home for most business logic.
  • Usage: All reusable, domain-specific logic should live here, not in function entrypoints or UI code.

Data Packages ​

@mmv3/db ​

  • Purpose: Handles database actions and migrations.
  • Special note: This package compiles Drizzle ORM migrations. Files with the .sql.ts extension must be compatible with Drizzle's migration compiler—be careful with imports and code in these files.

@mmv3/core-data ​

  • Purpose: Data modeling and data-related utilities that are logically separate from both core and db.
  • Usage: Use for data structures, validation, and helpers that don't belong in the main business logic or database layer.

SDK ​

@mmv3/sdk ​

  • Purpose: A client SDK for external consumers.
  • Note: This package is designed to be released separately from the rest of the monorepo, so it is kept isolated.
  • SDK Generation:
    • The SDK is generated using hey-api, which creates a TypeScript client from an OpenAPI spec.
    • Generated files are in packages/sdk/src/client (e.g., client.gen.ts, types.gen.ts, sdk.gen.ts).
    • To regenerate the SDK, run the hey-api CLI with your OpenAPI spec.
    • The SDK is designed to be published separately for external consumers.
    • See hey-api documentation for more information.

Frontend & UI Packages ​

@mmv3/www ​

  • Purpose: The main web client, built with TanStack Start.
  • Usage: All application-level frontend code.
  • Routing:
    • Uses TanStack Start and TanStack Router.
    • Routing is defined in packages/www/app/router.tsx and routeTree.gen.ts.
    • To add a new route, update the route tree and add a new file in packages/www/app/routes.
    • The router is created with:
ts
import { createRouter as createTanStackRouter } from "@tanstack/react-router";
import { routeTree } from "./routeTree.gen";
export function createRouter() {
  return createTanStackRouter({ routeTree });
}

@mmv3/ui ​

  • Purpose: Shared UI components and Storybook stories (React).
  • Usage: For reusable UI elements and design system components.
  • shadcn/ui:
    • We use shadcn/ui for our React component library.
    • The CLI is configured via the root components.json file, which specifies style, aliases, and Tailwind integration.
    • To add or build new components, use the shadcn/ui CLI. The CLI will use the configuration in components.json to scaffold components into packages/ui/src.
    • Example components.json settings:
      json
      {
  "style": "new-york",
  "tsx": true,
  "tailwind": {
    "css": "packages/ui/src/styles/global.css"
  },
  "aliases": {
    "components": "packages/ui/src"
  }
}
    • See shadcn/ui documentation for CLI usage.
  • Storybook:
    • We use Storybook for developing and testing UI components in isolation.
    • Storybook is configured in packages/ui/.storybook.
    • To run Storybook:
      sh
      nx run ui:storybook
    • Every component should have a corresponding .stories.tsx file to document its usage and states.
    • Stories help with visual testing, documentation, and design review.
  • TailwindCSS:
    • TailwindCSS is used for styling all UI components.
    • The main Tailwind CSS file for UI is at packages/ui/src/styles/global.css.
    • To use UI styles in other apps, import the UI styles in your app's CSS:
      css
      @import "@mmv3/ui/styles";
    • Example (from www/app/styles/app.css):
      css
      @import "tailwindcss" source("../../../");
@import "@mmv3/ui/styles";

@mmv3/blog ​

  • Purpose: The Astro-powered blog site.

@mmv3/docs ​

  • Purpose: The Astro-powered documentation site.

@mmv3/emails ​

  • Purpose: A development playground for email templates and scripts for acting on emails.
  • react-email:
    • We use react-email to build and preview email templates as React components.
    • Email templates are located in packages/emails/src/templates.
    • To add a new template, create a new .tsx file in the templates directory.
    • You can preview and test emails locally using the dev playground in the emails package.
    • Example template:
      tsx
      // packages/emails/src/templates/welcome.tsx
import { Html } from "@react-email/html";
export const WelcomeEmail = () => (
  <Html>
    <h1>Welcome!</h1>
  </Html>
);
    • See react-email documentation for more details.

@mmv3/reports ​

  • Purpose: A development playground for report templates and scripts for acting on reports.

Assets ​

@mmv3/assets ​

  • Purpose: Central location for importing images and other static assets.
  • Usage: Import assets from here in any package that needs them.

Summary ​

  • Business logic: core
  • Data modeling/actions: db, core-data
  • SDK: sdk (potentially published separately)
  • Frontend: www, ui, blog, docs, emails, reports
  • Assets: assets

This structure keeps concerns separated, makes code easier to maintain, and supports both internal and external consumers.