Skip to content

AGENTS.md

Latest commit

 

History

History
154 lines (117 loc) · 6.03 KB

AGENTS.md

File metadata and controls

154 lines (117 loc) · 6.03 KB
Raw

Solana.com Monorepo Agent Guide

Start here before exploring the repo in depth.

What This Repo Is

This is a pnpm workspace + Turborepo monorepo for several separately deployed Next.js apps that are stitched together behind solana.com with rewrites and asset prefixes.

Most apps are not standalone product islands. They share:

  • @workspace/i18n for locale config and routing helpers
  • @workspace/ui for reusable UI primitives
  • @solana-com/ui-chrome for shared header, footer, cross-app links, alerts, and Inkeep integrations
  • Turborepo tasks defined in the root package.json and turbo.json

Fast Routing Map

Pick the app first. That usually cuts exploration time in half.

Area Workspace Local Port Key Route Prefixes
Main marketing site apps/web / solana-com 3000 /, /solutions, /ecosystem, /events, selected /developers/* routes
Developer docs apps/docs / solana-docs 3003 /docs, /learn, /developers, /developers/cookbook, /developers/bootcamp
Media/blog apps/media / solana-com-media 3002 /news, /changelog, /reports, /upgrades, /podcasts, /keystatic
Templates showcase apps/templates / solana-templates 3001 /developers/templates via rewrites
Accelerate event site apps/accelerate / solana-com-accelerate 3004 /accelerate via rewrites
Breakpoint event site apps/breakpoint / solana-com-breakpoint 3005 /breakpoint via rewrites

Repo Layout

Apps

  • apps/web: main solana.com app, large surface area, mix of marketing, ecosystem, events, news aggregation, and developer entry points
  • apps/docs: Fumadocs-based developer docs with MDX content under content/
  • apps/media: Keystatic-backed news and podcast site with content in content/
  • apps/templates: templates browser that fetches metadata from GitHub
  • apps/accelerate: event microsite with its own asset prefix and route rewrites
  • apps/breakpoint: event microsite with its own asset prefix and route rewrites

Shared packages

  • packages/i18n: locale list, routing helpers, shared message loading
  • packages/ui: reusable UI primitives
  • packages/ui-chrome: shared nav/footer/theme/cross-app link behavior
  • packages/docs-examples: tested source snippets embedded in cookbook pages
  • packages/ecosystem-data: canonical company, wallet, and logo registry used by apps
  • packages/fab-menu: reusable Solana property menu
  • packages/sentry: shared Sentry helpers
  • packages/sitemap: shared sitemap generation helpers
  • packages/config-oxlint, packages/config-typescript: shared configs

First Commands To Reach For

From repo root:

pnpm install
pnpm dev
pnpm dev:web
pnpm dev:media
pnpm dev:acc
pnpm dev:bp
pnpm --filter solana-docs dev
pnpm --filter solana-templates dev
pnpm --filter solana-com-breakpoint dev
pnpm lint
pnpm test
pnpm --filter <workspace> lint
pnpm --filter <workspace> check-types
pnpm --filter <workspace> test

Periodic agent-doc refresh:

node skills/refresh-agent-context/scripts/workspace_inventory.mjs

Useful filters:

  • solana-com
  • solana-docs
  • solana-com-media
  • solana-templates
  • solana-com-accelerate
  • solana-com-breakpoint

Turborepo Rules That Matter

  • Root scripts call turbo run ...
  • build depends on ancestor build tasks and reads .env*
  • dev is uncached and persistent
  • test has no cached outputs
  • Shared env pass-through is declared in turbo.json

When a change needs validation, prefer targeted workspace commands before running the whole repo.

If repo structure changed and the onboarding docs may be stale, use the refresh-agent-context skill in skills/refresh-agent-context/.

Cross-App Behavior

  • Non-web apps set NEXT_PUBLIC_APP_NAME in next.config.ts
  • @solana-com/ui-chrome/url-config uses that value to decide whether a link should use Next client navigation or a full page load across app boundaries
  • Several apps use assetPrefix plus rewrites so they can live behind solana.com without breaking static assets

If you touch navigation, shared header/footer behavior, or route ownership, inspect packages/ui-chrome and the target app next.config.ts together.

Content Ownership

  • apps/docs/content: source of truth for docs, cookbook, learn, and developer bootcamp content
  • apps/media/content: source of truth for posts, podcasts, reports, upgrades, releases, authors, tags, and global CMS content
  • packages/i18n/messages/*: shared UI message catalogs by app
  • packages/ecosystem-data: shared company metadata, wallet-directory records, and logos, not app-specific marketing copy

Public Content Authoring

Before generating or materially rewriting reader-facing English copy, load and follow skills/solana-tone-of-voice/SKILL.md. This applies to UI strings, landing-page and documentation prose, Media content, metadata, CTAs, and social copy. Read the owning app's instructions as well; they may impose more specific content, source, or format requirements.

Styling Constraint

  • Use Tailwind utility classes for all styling changes on this branch.
  • CSS Modules (*.module.css) are not an option for new or modified surfaces; migrate existing module styles when touching that surface.

Best Next File

After reading this file:

  • open the target app's AGENTS.md if it exists
  • then open that app's package.json
  • then inspect next.config.ts

That usually gives enough context to make a safe first edit.