🛠️ Feature Development Workflow (Business Guide)

Target Audience: Developers building NEW business logic on Instant Ship™.

This guide explains how to migrate your mental model from "Traditional React" to the Instant Ship™ Engine. Follow these steps to ensure your new features benefit from the platform's automated SEO and performance optimizations.

---

1. Creating a New Page (e.g., "Dashboard")

In Instant Ship™, you do not touch a Router.tsx file. You create files.

Step A: Create the Route File

Create routes/$lang.dashboard.tsx. The $lang prefix ensures it automatically supports multi-language.

tsx
// routes/$lang.dashboard.tsx
import { createFileRoute } from '@tanstack/react-router';
import { useTranslation } from 'react-i18next';

// 1. Define the Route
export const Route = createFileRoute('/$lang/dashboard')({
  component: DashboardPage,
});

// 2. Build the Component
function DashboardPage() {
  const { t } = useTranslation();
  return (
    <div className="py-20 animate-fade-in">
      <h1 className="text-4xl font-black text-white">
        {t('dashboard.title')}
      </h1>
      {/* Your Business Logic Here */}
    </div>
  );
}

Step B: Register Metadata (Crucial for SEO)

Open site.config.ts and add your route to the routes array.

typescript
// site.config.ts
export const siteConfig = {
  // ...
  routes: [
    // ... existing routes
    { 
      path: "/dashboard", 
      titleKey: "dashboard.title", 
      descriptionKey: "dashboard.desc" 
    }
  ]
};

Step C: Add Translations

Open i18n.ts and add the keys for English (en) and Chinese (zh).

typescript
// i18n.ts
const resources = {
  en: {
    translation: {
      dashboard: {
        title: "User Dashboard",
        desc: "Manage your high-authority assets."
      }
    }
  },
  // ... repeat for zh
};

Done. The system will now:

1. Auto-generate the route URL /en/dashboard and /zh/dashboard.
2. Generate correct <title> and meta description tags.
3. Include the page in sitemap.xml on the next build.

---

2. Developing Business Components

Place reusable UI logic in components/.

Rule: Isolate Data & UI

• Bad: Fetching data directly inside a button component.
• Good: Passing data as props, or using a specialized Hook.

Example: components/dashboard/StatCard.tsx

tsx
import React from 'react';

interface StatCardProps {
  label: string;
  value: string;
  trend?: 'up' | 'down';
}

export const StatCard: React.FC<StatCardProps> = ({ label, value }) => (
  <div className="p-6 bg-slate-900 border border-white/10 rounded-2xl">
    <div className="text-slate-400 text-xs uppercase tracking-widest">{label}</div>
    <div className="text-3xl font-black text-white mt-2">{value}</div>
  </div>
);

---

3. Integrating Backend / AI Services

Use @google/genai or standard fetch within useEffect or React Query (Recommended).

Pattern: The "Service Hook"

Don't clutter your component with API calls. Create a custom hook.

tsx
// hooks/useGenerateReport.ts
import { useState } from 'react';
import { GoogleGenAI } from "@google/genai";

export const useGenerateReport = () => {
  const [loading, setLoading] = useState(false);
  
  const generate = async (prompt: string) => {
    setLoading(true);
    // Remember: process.env.API_KEY is available
    const ai = new GoogleGenAI({ apiKey: process.env.API_KEY });
    const response = await ai.models.generateContent({
      model: 'gemini-3-flash-preview',
      contents: prompt
    });
    setLoading(false);
    return response.text;
  };

  return { generate, loading };
};

---

4. Navigation & Linking (ID-First Protocol)

NEVER use <a> tags for internal links. It destroys the SPA experience and performance. ALWAYS pass the ID in the state when linking to a specific resource.

Correct Usage

tsx
import { Link } from '@tanstack/react-router';
import { useTranslation } from 'react-i18next';

function ResourceCard({ item }) {
  const { i18n } = useTranslation();
  
  return (
    // ✅ ID-First Linking
    <Link 
      to={`/${i18n.language}/docs/${item.slug}`} 
      state={{ prid: item.id } as any} // Pass ID for O(1) lookup
      className="text-primary hover:underline"
    >
      Read More
    </Link>
  );
}