Introduction to Swift Web

Swift Web is a Nuxt 4 full-stack framework designed for internal business projects. It consists of four parts: a scaffolding CLI, a core framework module, a Starter project template, and a Standards package. Its goal is to provide the team with a unified technical baseline and development standards, so every project can launch quickly and maintain consistent engineering quality.

Why Choose Swift Web

Swift Web is not "yet another component library plus a template". It was designed around three explicit goals, each addressing a real pain point of the legacy framework:

Performance: ISR caching first, no more 100% CPU

The legacy framework rendered every page with real-time SSR — under traffic, the Node server CPU was regularly maxed out. Swift Web makes the rendering strategy a first-class citizen: every page must explicitly declare one of ISR / SSR / CSR / SSG (enforced by ESLint; a missing declaration blocks the merge). ISR caching absorbs the vast majority of traffic, with full SSR reserved for the few pages that truly need it. Performance is not an afterthought to tune later — it is a forced decision the moment each page is born.

Core capabilities managed centrally, one upgrade benefits every project

Encrypted requests, the auto-login chain, chunked uploads, the full SEO suite, unified tracking, the ad foundation… all the capabilities that used to be rebuilt per project now live in @swift-web/framework, maintained in one place. A single dependency upgrade brings every project the latest features and fixes. Business freedom is not sacrificed: components ship unstyled (visuals belong to the project), and extension happens through thin wrappers rather than forked source edits — upgrading the framework never turns into merge hell.

AI-friendly: engineering constraints designed for AI-assisted development

This is where Swift Web earns its keep. From day one the rules were designed on the assumption that AI is one of the primary developers — clear, strict, and machine-verifiable, so AI produces predictable code inside the guardrails:

• A single source of truth for standards: development rules live in @swift-web/standards and are synced into every repo's CLAUDE.md — Claude Code / Cursor / Copilot read them out of the box, no tribal knowledge required
• Zero-config AI toolchain: projects generated by sw create ship with .mcp.json and complete AI convention files — AI works correctly from minute one of a new project
• Rules backed by mechanical enforcement: mandatory rendering strategy, mandatory SEO, strict root-class-to-filename mapping, encrypted cache utils only… the key rules come with ESLint / Stylelint / commit-hook enforcement, so AI mistakes fail fast instead of relying on human review
• Automated AI review on MRs: every merge request triggers a bot review with inline comments, auto-merging when clean — code written by AI gets reviewed by AI first

In one sentence: other frameworks solve "how humans write faster"; Swift Web also solves "how AI writes correctly".

Four Core Components

Swift Web Ecosystem

@swift-web/cli        CLI scaffolding tool (published to private npm)
  └─ sw create / add / config / info / upgrade / run

@swift-web/framework  Core framework module (published to private npm)
  └─ Components / Composable / Store / Plugin / Middleware / Module options

@swift-web/starter    Project template (published to private npm; pulled only by the cli, end-users never install it directly)
  └─ Fetched via `npm pack @swift-web/starter` when `sw create` runs

@swift-web/standards  Single source of truth for ecosystem standards (published to private npm)
  └─ Development rules / distributable ESLint / Prettier / Stylelint configs / commit-msg validation

@swift-web/cli

The command-line tool with the binary name sw. Handles project initialization, file generation, configuration management, script execution, AI integration, and version upgrade checks. Install once globally and it works for all projects.

pnpm add -g @swift-web/cli
sw create YC001-WEB-my-project
sw add page product-detail
sw upgrade

@swift-web/framework

The core framework in Nuxt Module form, integrated via modules: ['@swift-web/framework']. Provides foundational capabilities shared across all projects, with centralized version management — upgrade once and all projects benefit.

Framework built-in capabilities at a glance:

@swift-web/starter (project template)

The starter is an npm package (published to the verdaccio private registry npm.djatm.cloud), but end-users never install it directly — sw create fetches it at runtime via npm pack @swift-web/starter. Includes a complete Nuxt 4 project configuration, CI/CD scripts (GitLab CI + PM2), ESLint / Stylelint rules (consuming the @swift-web/standards base), and Vitest unit-test + Playwright E2E skeletons — no manual configuration required.

@swift-web/standards (standards)

The single source of truth for ecosystem standards: the development SOP, AI collaboration conventions, and commit / branch rules are maintained centrally in rules/ and synced into the CLAUDE.md of framework / starter / docs and every business project, so all repos read the same rules. It also publishes distributable ESLint / Prettier / Stylelint base configs and a commit-msg validation script, consumed as import base from '@swift-web/standards/eslint'. Upgrading a rule means one release at the source — the whole ecosystem picks it up on the next dependency upgrade. See Development Standards.

Framework Capabilities in Detail

40+ Built-in Components

All framework components use the Sw prefix and are auto-imported by Nuxt — no manual import needed. Grouped by family:

Base UI

Overlays & Feedback

Media Playback

Rails / Carousels / Video Feed (choose by "how content flows")

Upload / QR Code / Rich Text

Ad Primitives (self-rendering + built-in impression / click tracking, see Ad Components & Tracking; generic tracking lives in the Tracking Foundation)

Theme / Language

PWA Guide

17 Composables

// Login & auth
useLoginCheck() // Check login state, redirect if not logged in
useLoginBy() // Multi-method login (phone number / account password, etc.)
useLoginDialog() // Show login dialog
useAuthReady() // Wait until the login flow finishes (device + credential attempt done)

// UI interactions
useModal() // Imperative modal
useToast() // Toast notifications (success / error / warning)

// Media / upload / decryption
useUploader() // Chunked file upload
useDecryptedAsset() // Decrypt encrypted assets (.bnc) + IndexedDB cache

// Theme
useTheme() // Theme management (mode-aware: resolvedTheme + toggle/system/dark/light; registered unconditionally)

// SEO
useSeo() // Unified SEO entry (og / canonical / JSON-LD / robots)

// Tracking & ads
useTracker() // Group-wide WebSDK tracking (track custom events)
useAdTrack() // Auto-assembles ad impression / click tracking fields
useAdFrequency() // Ad display frequency control (encrypted cache)
useExposure() // Generic expose-once-on-viewport-entry detection (content card exposure / own-SDK escape hatch)

// PWA
useAddToHomescreen() // Add-to-home-screen (A2HS) capability detection & trigger

// Interaction / navigation
useHoverPreview() // Mechanism layer for hover-to-preview overlays (intent state machine + positioning pure fn)
useExternalRedirect() // External-link interstitial: allowlist check + noindex + countdown redirect
useVideoPlayerPrefs() // Player preferences: skip intro & credits / autoplay next episode

useLocal / useSession (encrypted local cache) are classified as utility functions; useUserStore / useSystemStore are global stores — see the next two sections.

2 Global Stores

useUserStore() // User info (login state, token, user profile)
useSystemStore() // System info (global config injected server-side)

9 Plugins

15 Module Options

Configured via the swiftConfig key in nuxt.config.ts (full reference: framework/module-options):

swiftConfig: {
  theme: { mode: 'toggle' },                          // Theme mode (system/toggle/dark/light)
  i18n: { enabled: true, defaultLocale: 'zh-CN' },   // Internationalization
  pwa: true,                                          // PWA
  auth: {                                             // Route guard + client auth init
    guardedPaths: ['/mine'],
    guestPaths: ['/login', '/register'],
  },
  obfuscate: true,                                    // JS obfuscation (enabled by default in production)
  websocket: true,                                    // WebSocket client
  errorHandler: { enabled: true, endpoint: '/_error-report' },  // Global error monitoring
  styles: { reset: true, responsive: true },          // CSS base-layer injection toggles
  systemInfo: true,                                   // /system/info fetch (false / object optional)
  suppressConsole: true,                              // Disable console in production
  image: { provider: 'noop' },                        // SwImage provider routing
  manualChunks: {},                                   // Vite custom chunk-split rules
  request: { timeout: 20_000 },                       // $request global timeout / headers
  seo: {                                              // SEO suite (permanently enabled)
    aiBotPolicy: 'allow',                             // AI training bot policy ('allow' | 'disallow')
    sitemap: { exclude: ['/preview/**'] },            // Extra sitemap exclude paths (private paths excluded by default)
  },
  tracker: true,                                      // Group-wide tracking foundation (auto-degrades silently if unconfigured)
}

Project Architecture

project-directory/
├── app/
│   ├── components/      Business components (PascalCase naming)
│   ├── pages/           Route pages (kebab-case naming)
│   ├── layouts/         Layout files (all lowercase naming)
│   ├── composables/     Business-level composables
│   ├── store/           Business-level Pinia store
│   ├── api/             API modules (split by feature)
│   ├── assets/          CSS variables, global styles
│   └── plugins/         Business-level plugins
├── public/
│   └── images/          Image source files (jpg/png/webp/svg)
├── i18n/                Internationalization translation files (zh-CN/zh-TW/en)
├── server/              Nitro server-side API
├── .env                 Local environment variables (not committed to git)
├── nuxt.config.ts       Nuxt config (includes framework module options)
└── swift.config.json    Swift Web project metadata

Layering Principles

┌─────────────────────────────────────────┐
│           Business layer (starter)      │
│   app/pages → app/components → app/api │
│              ↓ uses (auto-imported)     │
├─────────────────────────────────────────┤
│          Framework layer (framework)    │
│   Sw* components / use* composables / store │
│      Must not reverse-reference the business layer │
└─────────────────────────────────────────┘

Integrated Third-Party Modules

The framework automatically installs and configures the following modules — business projects do not need to configure them again:

Use Cases

Swift Web is designed specifically for internal business projects and is suitable for:

• Admin dashboards and back-office systems
• User-facing web applications (content platforms, membership systems, etc.)
• Marketing pages or landing pages that require SEO
• Internationalized applications with multi-language requirements

Prerequisites

Next steps

• Quick start — create a project and get it running in 5 minutes
• Development standards — team conventions (naming / rendering strategy / SEO / SSR safety)
• Module Options — overview of all swiftConfig capabilities
• Nuxt rendering modes guide — the rationale behind the framework's "ISR-first" performance goal