Skip to content

development-guide.md

Latest commit

 

History

History
360 lines (263 loc) · 9.62 KB

development-guide.md

File metadata and controls

360 lines (263 loc) · 9.62 KB
Raw

Development Guide

Prerequisites

Before starting development, ensure you have the following tools installed:

  • Node.js (latest LTS version recommended)
  • pnpm package manager

Getting Started

Initial Setup

  1. Clone the repository

  2. Install dependencies:

    pnpm i

  3. Start the development server:

    pnpm run dev

The development server will start TinaCMS in development mode with Next.js and provide a local URL for testing.

Technology Stack

Core Technologies

  • Next.js 15 - React framework with App Router architecture
  • TinaCMS - Git-based headless CMS for content management
  • TypeScript - Type-safe JavaScript development
  • Tailwind CSS - Utility-first CSS framework
  • shadcn/ui - Component library built on Radix UI
  • Lucide React - Icon library

Project Architecture

loqus-landing/
├── app/                    # Next.js App Router pages
│   ├── layout.tsx         # Root layout
│   ├── page.tsx           # Homepage
│   ├── blog/              # Blog routes
│   └── [...urlSegments]/  # Dynamic routes
├── components/            # Reusable React components
│   ├── custom/           # Custom business components
│   ├── icons/            # SVG icon components
│   ├── illustrations/    # Complex illustrations
│   ├── layouts/          # Layout components
│   ├── sections/         # Page section components
│   └── ui/               # shadcn/ui components
├── content/              # TinaCMS content files
│   ├── blog/            # Blog posts (JSON)
│   ├── general/         # General settings
│   └── pages/           # Page content
├── tina/                # TinaCMS configuration
│   ├── collection/      # Content collection schemas
│   └── config.tsx       # Main TinaCMS config
├── lib/                 # Utility functions and constants
└── public/              # Static assets

Development Workflow

Branch Management

All changes must be made in feature branches:

  1. Create a new branch from main:

    git checkout -b feature/your-feature-name

  2. Make your changes locally

  3. Test thoroughly using the development server

  4. Commit your changes with descriptive messages using conventional commits:

    git commit -m "feat(components): ✨ add new hero section component"

  5. Push the branch to GitHub:

    git push origin feature/your-feature-name

  6. Create a Pull Request on GitHub

Automated Deployment

Development Deployment (PR Preview)

When you create a PR, GitHub Actions automatically:

  1. Builds the site with changes from your branch using pnpm run build
  2. Configures TinaCMS for the preview branch
  3. Exports static files to ./out directory
  4. Commits build artifacts to the preview branch
  5. Deploys to GitHub Pages at https://3jane.github.io/loqus-landing
  6. Adds a comment to the PR with preview and admin links

Environment variables for preview builds:

  • NEXT_PUBLIC_BASE_PATH=/loqus-landing (GitHub Pages subdirectory)
  • Development analytics keys
  • Branch-specific TinaCMS configuration

Production Deployment

After merging to main, GitHub Actions automatically:

  1. Builds the production site from merged changes
  2. Uses production environment variables
  3. Triggers Digital Ocean deployment
  4. Publishes to https://loqus.ai

Production environment uses:

  • NEXT_PUBLIC_BASE_PATH=/ (root domain)
  • Production analytics keys
  • Main branch TinaCMS configuration

Content Management with TinaCMS

Content Structure

Content is managed through TinaCMS and stored in the content/ directory:

content/
├── blog/           # Blog posts (JSON format)
├── general/        # Site-wide settings and data
└── pages/          # Page-specific content
    ├── blog/       # Blog listing page
    ├── l/          # Landing pages
    └── index.json  # Homepage content

TinaCMS Collections

Collections are defined in tina/collection/:

  • GeneralCollection (general.ts) - Site-wide settings, navigation, footer
  • PageCollection (page.ts) - Page content with dynamic sections
  • BlogCollection (blog.ts) - Blog posts with metadata and content

Content Editing

  1. Local Development: Access TinaCMS admin at http://localhost:3000/admin
  2. Preview Environment: Access admin at https://3jane.github.io/loqus-landing/admin
  3. Production: Access admin at https://loqus.ai/admin

Adding New Content Types

To add a new content collection:

  1. Create collection schema in tina/collection/new-collection.ts:

    import { Collection } from "tinacms";

export const NewCollection: Collection = {
  name: "newContent",
  label: "New Content",
  path: "content/new-content",
  fields: [
    {
      type: "string",
      name: "title",
      label: "Title",
      required: true,
    },
    // Add other fields
  ],
};

  2. Register in main config (tina/config.tsx):

    import { NewCollection } from "./collection/new-collection";

const config = defineConfig({
  schema: {
    collections: [GeneralCollection, PageCollection, BlogCollection, NewCollection],
  },
});

  3. Create content directory:

    mkdir content/new-content

Component Development

Component Architecture

Components follow a modular structure:

components/
├── custom/          # Business-specific components
│   ├── component.tsx
│   └── index.ts    # Re-exports
├── sections/        # Page sections with schema + view pattern
│   └── section-name/
│       ├── section-name.schema.ts  # TinaCMS field definitions
│       ├── section-name.view.tsx   # React component
│       └── index.ts                # Re-exports
└── ui/             # shadcn/ui base components

Section Components

Page sections follow a standardized pattern:

  1. Schema file (.schema.ts) - Defines TinaCMS fields
  2. View file (.view.tsx) - React component implementation
  3. Index file (.ts) - Clean re-exports

Example section structure:

// hero-section.schema.ts
export const heroSectionSchema = {
  type: "object",
  label: "Hero Section",
  name: "heroSection",
  fields: [
    {
      type: "string",
      label: "Title",
      name: "title",
    },
  ],
};

// hero-section.view.tsx
export const HeroSectionView = ({ data }) => {
  return <section>{data.title}</section>;
};

// index.ts
export { heroSectionSchema } from "./hero-section.schema";
export { HeroSectionView } from "./hero-section.view";

Environment Configuration

Environment Variables

Required environment variables:

# TinaCMS Configuration
NEXT_PUBLIC_TINA_CLIENT_ID=your_tina_client_id
NEXT_PUBLIC_TINA_BRANCH=main  # or feature branch for development
TINA_TOKEN=your_tina_token

# Deployment Configuration
NEXT_PUBLIC_BASE_PATH=/  # Production: /, Preview: /loqus-landing

# Analytics (optional)
NEXT_PUBLIC_SEGMENT_KEY=your_segment_key
NEXT_PUBLIC_SEGMENT_HOST=your_segment_proxy_host

Base URL Handling

Critical: The application handles different base URLs automatically:

  • Production (https://loqus.ai): Uses / as base path
  • GitHub Pages Preview (https://3jane.github.io/loqus-landing): Uses /loqus-landing/ as base path

Asset references are handled automatically by Next.js configuration.

Build Scripts

Available npm scripts:

# Development with TinaCMS
pnpm run dev

# Production build
pnpm run build

# Local build (skips cloud checks)
pnpm run build-local

# Start production server
pnpm run start

# Static export
pnpm run export

# Linting
pnpm run lint

Pre-Merge Checklist

Before creating a PR, verify:

  • Development server runs without errors (pnpm run dev)
  • Production build succeeds (pnpm run build)
  • All TypeScript errors resolved
  • Components render correctly on different screen sizes
  • TinaCMS admin interface works with new content types
  • Content editing flows work as expected
  • No console errors or warnings
  • Changes are tested locally
  • Code follows project conventions
  • Commit messages follow conventional commit format

PR Review Process

  1. Create PR with descriptive title and description
  2. Wait for automated build and preview deployment
  3. Test on GitHub Pages preview using provided links:
  4. Request review from team members
  5. Address feedback and update as needed
  6. Merge after approval and successful automated tests

Troubleshooting

Common Issues

  1. TinaCMS Authentication Errors

    • Verify TINA_TOKEN and NEXT_PUBLIC_TINA_CLIENT_ID are set
    • Check branch configuration matches NEXT_PUBLIC_TINA_BRANCH

  2. Build Failures

    • Run pnpm run build-local to skip cloud checks during development
    • Ensure all TypeScript errors are resolved

  3. Asset Loading Issues

    • Verify assets are in the public/ directory
    • Check base path configuration for different environments

  4. Preview Deployment Issues

    • Verify GitHub Actions have proper secrets configured
    • Check workflow logs in GitHub Actions tab

Getting Help

For additional support:

  1. Check existing GitHub Issues
  2. Review TinaCMS documentation at https://tina.io/docs
  3. Consult Next.js documentation at https://nextjs.org/docs