Analog User Guide - Tech Stack

Analog Starter is a content-driven Next.js project. Shared application code lives under src, while each site keeps its content, configuration, and public assets under sites.

This page gives a high-level overview of the technologies used by the project. Exact package versions are available in package.json.

At a glance

Application foundation

Next.js and React

Next.js provides the application framework. The project uses the App Router for pages, layouts, dynamic content routes, metadata, images, fonts, and production builds.

React provides the component model used throughout the interface. Interactive features such as search, navigation, theme controls, and comments use client-side components where necessary, while most content rendering remains server-side.

TypeScript and Zod

TypeScript is used for application code and site configuration.

Zod validates values read from site.config.ts, MDX frontmatter, home.mdx, news.yml, and people.yml. This allows content errors to be reported during development or builds rather than appearing as broken pages later.

Users do not need to understand the schemas to write content. The accepted fields are documented in Site Configuration and Content Model.

Interface and styling

Tailwind CSS

Tailwind CSS provides the styling foundation. Components use semantic utilities connected to shared design tokens, including:

bg-background
text-foreground
text-muted-foreground
border-border

The color palette, fonts, and rounded corners can therefore be changed from a small set of CSS variables. These common changes are covered in Customization.

shadcn/ui and Base UI

shadcn/ui components are stored as source files in the repository rather than provided by a runtime component package. They can be adjusted alongside the rest of the interface.

Base UI supplies lower-level behavior and accessibility for interactive elements such as dialogs, menus, checkboxes, and tooltips.

Most icons come from Tabler Icons. Light and dark themes are managed through @wrksz/themes and CSS design tokens.

Content system

Content Collections

Content Collections reads and validates the files belonging to the selected site.

The current model includes:

• posts and general pages;
• internal author profiles;
• homepage content and sections;
• optional news and people data.

Content Collections also compiles MDX and makes the resulting content available to the Next.js routes. The file locations and accepted fields are described in Content Model.

MDX

MDX combines Markdown with React components. Ordinary articles can be written with familiar Markdown syntax, while a small number of components can be inserted when needed.

The current pipeline supports:

• GitHub Flavored Markdown;
• inline and display mathematics through KaTeX;
• GitHub-style alert blocks;
• syntax-highlighted code;
• local article images;
• heading links and tables of contents;
• Twemoji rendering.

Rendered examples are available in Markdown Basic Syntax. The complete list of Markdown-related packages is available in package.json.

Site features

The built-in search dialog uses cmdk and searches across the content available to the active site.

Comments are optionally provided through Giscus, analytics through Umami, and the feed package generates /rss.xml. Their user-facing setup is covered in Integrations.

Next.js metadata APIs generate page descriptions, canonical URLs, robots directives, Open Graph metadata, Twitter cards, and favicon declarations from the validated site and content data.

Developer tooling

Bun is used to install packages and run the development and build scripts.

Oxlint checks JavaScript and TypeScript source code, while Oxfmt formats source files and supported content formats.

The commands needed for local development are introduced in Getting Started.

Why this architecture?

The current stack is the result of several rounds of implementation rather than a collection of tools selected all at once.

From Chakra UI to Tailwind CSS and shadcn/ui

Earlier versions of the project used Chakra UI. It provided a convenient component library and a consistent styling API during the initial development of the site.

The project later moved to Tailwind CSS, shadcn/ui, and lower-level component primitives. The change makes component styles visible in the source, keeps the reusable component code inside the repository, and reduces dependence on the design decisions of one UI library.

AI-assisted development was another practical consideration. Tailwind CSS and shadcn/ui are widely used in current React projects, so coding models generally have more public examples and established patterns to draw from.

Separating the application from site content

The other central choice is the separation between src and sites:

src/                 Shared application code
sites/demo/          Demo content and documentation
sites/another-site/  Content and configuration for another site

Routes, components, schemas, and shared behavior remain under src. Each site provides its own content, public assets, site configuration, and optional Next.js configuration.

This keeps site-specific material out of the shared application and allows the same codebase to support a personal blog, a project site, or a research-group website.