Structure du projet

Vue d’ensembleLien vers la section

Starter Free est structuré pour clarté et évolution à long terme.

Ce n'est pas un dossier de démo. C'est un architecture adaptées à la production conçu pour vous aider à étendre les fonctionnalités sans transformer les pages en fichiers volumineux et fragiles.

Comprendre la structure tôt vous aide à:

• Étendre les fonctionnalités proprement
• garder les routes lisibles
• fil backend progressivement
• éviter les refactors causés par des responsabilités mixtes

Modèle mentalLien vers la section

Les pages définissent les routes. Les composants définissent les caractéristiques. UI définit les primitives.

Premiers points de personnalisationLien vers la section

Les chemins ici sont relatifs à votre paiement Starter Free. Dans la source monorepo, ce checkout est apps/starter-free; n'importez pas les paquets privés de monorepo dans le starter livré indépendamment.

Gardez le bootstrap d'apparence et le contrôle de thème existant lors du changement de marque. Le guide du tableau de bord ne suit pas l'achèvement ou l'état du projet. Essayez le Workflow de première session avant de modifier la fonctionnalité du projet.

StructureLien vers la section

Cette structure est intentionnellement petite. Il sépare la propriété de la route de la composition des fonctionnalités.

Flux d'architectureLien vers la section

App Router pages
  ↓
Feature components
  ↓
PyColors UI primitives

Une page doit décrire la surface du produit. Les composants de fonctionnalité doivent posséder des interactions. Les primitives UI doivent rester réutilisables et apatrides.

App directoryLien vers la section

Les app/ répertoire est la couche de routage. Les (app) Le groupe de routes fournit le shell d'application sans ajouter (app) à l'URL. Par exemple, app/(app)/projects/page.tsx sert /projects, et le niché [id]/page.tsx sert un ID de projet réel sélectionné dans la liste.

app/(app)/projects/layout.tsx monts ProjectProvider pour les routes de liste et de détail. Conservez cette limite partagée afin que la navigation ne crée pas un deuxième magasin de projets déconnecté. Le tableau de bord reste un composant serveur ; la page Projets existante et le fournisseur utilisent une limite client pour l'état local.

Il définit:

• auth points d'entrée
• pages de tableau de bord
• routes des produits
• paramètres et surfaces de facturation
• composition de mise en page de haut niveau

Répertoire des composantsLien vers la section

Les components/ Le répertoire contient des blocs de construction au niveau des fonctionnalités.

Par exemple, la fonctionnalité de projets conserve son fournisseur local de navigateur, le rendu de table, les actions de ligne, les boîtes de dialogue et les types d'échantillons ensemble.

Un extrait de composition ciblé de la page Projets transmet l'état actuel et les rappels à la table :

"use client";

import { ProjectTable } from "@/components/projects/project-table";
import { useProjects } from "@/components/projects/project-provider";

export function ProjectList() {
  const { projects, isLoading, renameProject, deleteProject } = useProjects();

  return (
    <ProjectTable
      projects={projects}
      isLoading={isLoading}
      onRename={renameProject}
      onDelete={deleteProject}
    />
  );
}

Cet extrait ne remplace pas la page complète. Conserver ses contrôles de création/réinitialisation, avis de stockage, liens de détails, et PageShell. Rendre un tel consommateur seulement en dessous de l'existant ProjectProvider; useProjects sortir de ce contexte. Réutilisez les boîtes de dialogue et les actions de ligne livrées au lieu de les remplacer par des composants réservés.

Fausse stratégie de donnéesLien vers la section

Les exemples de projet sont des données initiales / réinitialisées, pas la seule source de vérité après qu'un utilisateur modifie un projet. Le flux de courant est:

ProjectProvider
  -> read saved browser-local projects (or initial samples)
  -> expose projects, loading, storage notice, and mutation callbacks
  -> create / rename / delete -> update state and attempt localStorage write
  -> confirmed Reset demo -> replace local projects with original samples

components/projects/project-types.ts Possède le complet Project type et MOCK_PROJECTS. Réutilisez ce type au lieu de copier une interface réduite. components/projects/project-provider.tsx possède l'état de React et les mutations; lib/project-storage.ts possède la lecture / écriture des enregistrements de projet stockés.

Changement MOCK_PROJECTS ne remplace pas une collection de projets enregistrée valide. Utilisez la confirmation Réinitialiser démo action uniquement lorsque vous avez l'intention de rejeter les modifications locales. Les données enregistrées non valides reviennent à des échantillons avec un avis. Lorsque le stockage du navigateur n'est pas disponible, les modifications restent en mémoire pour la visite en cours uniquement. Il ne s'agit pas d'une base de données partagée, d'une authentification ou d'une synchronisation entre appareils.

Plus tard, remplacez cette limite de persistance locale du navigateur par vos propres opérations de projet de validation, d'autorisation et de sauvegarde de base de données côté serveur. Gardez les composants de présentation séparés de cette intégration spécifique au produit.

Modèle PageShellLien vers la section

Les pages SaaS principales utilisent un shell partagé pour une structure de page cohérente.

import { PageShell } from "@/components/app/page-shell";

export function ReportsPreview() {
  return (
    <PageShell title="Reports" description="Explore your report layout.">
      <p>No reports yet.</p>
    </PageShell>
  );
}

Utilisez ce modèle pour conserver :

• Espacement des pages cohérent
• En-têtes prévisibles
• actions alignées
• Métadonnées structurées

Ne le contournez pas à moins que la page ait vraiment besoin d'une mise en page différente.

Dialog patternLien vers la section

Les boîtes de dialogue sont isolées de la page et contrôlées par leur fonction parent.

Propriété recommandée:

Cela rend les flux de renommage et de suppression plus faciles à câbler plus tard sans changer la structure de la page.

Ajouter une nouvelle fonctionnalitéLien vers la section

Commencez par une route statique dans le shell d'application existant. Ce sont de nouveaux fichiers d'exemple à créer dans votre copie du dépôt, pas des fichiers déjà inclus dans Free. Aucun backend ou modèle d'autorisation n'est introduit par cet exemple.

mkdir -p 'app/(app)/reports' components/reports

export function ReportPanel() {
  return <p>No reports yet. Connect your own report data when ready.</p>;
}

import { PageShell } from "@/components/app/page-shell";
import { ReportPanel } from "@/components/reports/report-panel";

export default function ReportsPage() {
  return (
    <PageShell title="Reports" description="Your product reports.">
      <ReportPanel />
    </PageShell>
  );
}

Guide de décisionLien vers la section

Utilisez la structure Starter Free si :

• vous voulez des fichiers de route minces
• Les fonctionnalités doivent évoluer de manière indépendante
• Les données simulées deviendront plus tard des données backend.
• Les dialogues et les actions en ligne doivent rester réutilisables
• vous voulez un chemin clair de la surface frontale au câblage de production

Évitez de modifier la structure si :

• vous n'avez pas encore exploré la tranche verticale complète
• le changement ne sauve que quelques lignes aujourd'hui
• La route commencerait à posséder trop de logique
• Les primitives de l'interface utilisateur commenceraient à récupérer des données
• la couche simulée deviendrait dispersée globalement

Câblage backend plus tardLien vers la section

Lorsque vous connectez un backend, la structure reste familière.

L'objectif est de réutiliser la présentation tout en implémentant une frontière de produit réelle, pas simplement remplacer un appel de base de données pour le stockage local. Starter Pro fournit des fondations connectées configurables, pas une migration automatique des projets Free. Réexamen Ce qui est inclus et les Guide de mise à niveau avant de planifier votre intégration.

Questions courantesLien vers la section

Prochaines étapesLien vers la section