Added project pages and cards, most of the screens in chris samuels figma design document. Still need to implement project initialization modal and walkthrough, connect to backend and connect to wallet (maybe be beyond scope of this project)
This commit is contained in:
@@ -0,0 +1,257 @@
|
||||
# Component Migration List
|
||||
|
||||
This document outlines all components that need to be migrated from the original repo to the new monorepo, following our React Component Organization Conventions.
|
||||
|
||||
## Original Repository Path
|
||||
|
||||
All original components are located at:
|
||||
```
|
||||
/Users/ianlylesblx/IDEA_CORE/laconic/repos/snowballtools-base/packages/frontend/src/components
|
||||
```
|
||||
|
||||
## Migration Guidelines
|
||||
|
||||
1. **Styling Approach**:
|
||||
- Replace all CSS imports (e.g., `'react-dropdown/style.css'`) with Tailwind classes
|
||||
- Convert inline styles to Tailwind classes where possible
|
||||
- Use existing UI components from `components/ui` directory instead of external libraries
|
||||
|
||||
2. **Dependencies**:
|
||||
- Do not add new libraries to the project
|
||||
- Replace external component libraries with our own UI components
|
||||
- If a component depends on an external library, check if we have an equivalent in our UI library
|
||||
|
||||
3. **Pattern Matching**:
|
||||
- Follow existing patterns in our codebase for styling, state management, etc.
|
||||
- Use React hooks consistent with what's used in the rest of the application
|
||||
|
||||
4. **No Commits**:
|
||||
- All changes should be reviewed before being committed
|
||||
|
||||
## Feature-Based Organization
|
||||
|
||||
Components will be organized into the following feature groups:
|
||||
|
||||
## 1. Core Components
|
||||
|
||||
### Generic Components
|
||||
| Component | Current Path | Migration Status | Notes |
|
||||
|-----------|-------------|-----------------|-------|
|
||||
| Dropdown | `/components/Dropdown.tsx` | ✅ Completed | Simple dropdown component |
|
||||
| FormatMilliSecond | `/components/FormatMilliSecond.tsx` | ✅ Completed | Utility component for time formatting |
|
||||
| Logo | `/components/Logo.tsx` | ✅ Completed | Brand element |
|
||||
| SearchBar | `/components/SearchBar.tsx` | ✅ Completed | Generic search component |
|
||||
| Stepper | `/components/Stepper.tsx` | ✅ Completed | Progress indicator |
|
||||
| StopWatch | `/components/StopWatch.tsx` | ✅ Completed | Time tracking component |
|
||||
| VerticalStepper | `/components/VerticalStepper.tsx` | ✅ Completed | Vertical orientation of stepper |
|
||||
|
||||
## 2. Layout Feature
|
||||
|
||||
### Navigation Components
|
||||
| Component | Current Path | Migration Status | Notes |
|
||||
|-----------|-------------|-----------------|-------|
|
||||
| GitHubSessionButton | `/components/layout/navigation/components/GitHubSessionButton.tsx` | ✅ Completed | GitHub session management |
|
||||
| LaconicIcon | `/components/layout/navigation/components/LaconicIcon.tsx` | ✅ Completed | Brand icon |
|
||||
| NavigationActions | `/components/layout/navigation/components/NavigationActions.tsx` | ✅ Completed | Navigation action buttons |
|
||||
| WalletSessionId | `/components/layout/navigation/components/WalletSessionId.tsx` | ✅ Completed | Implemented in both layout/navigation and foundation/wallet-session-id |
|
||||
|
||||
### Screen Header Components
|
||||
| Component | Current Path | Migration Status | Notes |
|
||||
|-----------|-------------|-----------------|-------|
|
||||
| ActionButton | `/components/layout/screen-header/ActionButton.tsx` | ❌ Not Planned | Header action button - Skipping per instructions |
|
||||
| Header | `/components/layout/screen-header/Header.tsx` | ❌ Not Planned | Page header component - Skipping per instructions |
|
||||
|
||||
### Screen Wrapper Components
|
||||
| Component | Current Path | Migration Status | Notes |
|
||||
|-----------|-------------|-----------------|-------|
|
||||
| TabWrapper | `/components/layout/screen-wrapper/TabWrapper.tsx` | ❌ Not Planned | Tab content wrapper - Skipping per instructions |
|
||||
|
||||
### Search Components
|
||||
| Component | Current Path | Migration Status | Notes |
|
||||
|-----------|-------------|-----------------|-------|
|
||||
| ProjectSearchBar | `/components/layout/search/ProjectSearchBar/ProjectSearchBar.tsx` | ✅ Completed | Implemented in /components/foundation/project-search-bar with simplified functionality |
|
||||
| ProjectSearchBarDialog | `/components/layout/search/ProjectSearchBar/ProjectSearchBarDialog.tsx` | ❌ Not Planned | Search dialog - Skipping per instructions |
|
||||
| ProjectSearchBarEmpty | `/components/layout/search/ProjectSearchBar/ProjectSearchBarEmpty.tsx` | ❌ Not Planned | Empty state - Skipping per instructions |
|
||||
| ProjectSearchBarItem | `/components/layout/search/ProjectSearchBar/ProjectSearchBarItem.tsx` | ❌ Not Planned | Search result item - Skipping per instructions |
|
||||
|
||||
## 3. Project Management Feature
|
||||
|
||||
### Project Card Components
|
||||
| Component | Current Path | Migration Status | Notes |
|
||||
|-----------|-------------|-----------------|-------|
|
||||
| ProjectCard | `/components/projects/ProjectCard/ProjectCard.tsx` | ❌ Not Planned | Project display card - Skipping per instructions |
|
||||
| ProjectCardActions | `/components/projects/ProjectCard/ProjectCardActions.tsx` | ❌ Not Planned | Card actions - Skipping per instructions |
|
||||
| ProjectDeploymentInfo | `/components/projects/ProjectCard/ProjectDeploymentInfo.tsx` | ❌ Not Planned | Deployment info display - Skipping per instructions |
|
||||
| ProjectStatusDot | `/components/projects/ProjectCard/ProjectStatusDot.tsx` | ❌ Not Planned | Status indicator - Skipping per instructions |
|
||||
|
||||
### Project Search Components
|
||||
| Component | Current Path | Migration Status | Notes |
|
||||
|-----------|-------------|-----------------|-------|
|
||||
| ProjectSearchBar | `/components/projects/ProjectSearchBar/ProjectSearchBar.tsx` | ❌ Not Planned | **DUPLICATE** - Skipping per instructions |
|
||||
|
||||
### Project Settings Components
|
||||
| Component | Current Path | Migration Status | Notes |
|
||||
|-----------|-------------|-------|-------|
|
||||
| AddEnvironmentVariableRow | `/components/projects/project/settings/AddEnvironmentVariableRow.tsx` | ❌ Not Planned | Environment variable form - Skipping per instructions |
|
||||
| AddMemberDialog | `/components/projects/project/settings/AddMemberDialog.tsx` | ❌ Not Planned | Add team member - Skipping per instructions |
|
||||
| DeleteProjectDialog | `/components/projects/project/settings/DeleteProjectDialog.tsx` | ❌ Not Planned | Project deletion confirmation - Skipping per instructions |
|
||||
| DisplayEnvironmentVariables | `/components/projects/project/settings/DisplayEnvironmentVariables.tsx` | ❌ Not Planned | Environment variable display - Skipping per instructions |
|
||||
| DomainCard | `/components/projects/project/settings/DomainCard.tsx` | ❌ Not Planned | Domain display - Skipping per instructions |
|
||||
| EditDomainDialog | `/components/projects/project/settings/EditDomainDialog.tsx` | ❌ Not Planned | Domain editing - Skipping per instructions |
|
||||
| EditEnvironmentVariableRow | `/components/projects/project/settings/EditEnvironmentVariableRow.tsx` | ❌ Not Planned | Edit environment variable - Skipping per instructions |
|
||||
| GitSelectionSection | `/components/projects/project/settings/GitSelectionSection.tsx` | ❌ Not Planned | Git repository selection - Skipping per instructions |
|
||||
| MemberCard | `/components/projects/project/settings/MemberCard.tsx` | ❌ Not Planned | Team member display - Skipping per instructions |
|
||||
| ProjectSettingContainer | `/components/projects/project/settings/ProjectSettingContainer.tsx` | ❌ Not Planned | Settings container - Skipping per instructions |
|
||||
| ProjectSettingHeader | `/components/projects/project/settings/ProjectSettingHeader.tsx` | ❌ Not Planned | Settings header - Skipping per instructions |
|
||||
| RepoConnectedSection | `/components/projects/project/settings/RepoConnectedSection.tsx` | ❌ Not Planned | Repository connection status - Skipping per instructions |
|
||||
| SetupDomain | `/components/projects/project/settings/SetupDomain.tsx` | ❌ Not Planned | Domain setup flow - Skipping per instructions |
|
||||
| WebhookCard | `/components/projects/project/settings/WebhookCard.tsx` | ❌ Not Planned | Webhook display - Skipping per instructions |
|
||||
|
||||
### Project Overview Components
|
||||
| Component | Current Path | Migration Status | Notes |
|
||||
|-----------|-------------|-------|-------|
|
||||
| Activity | `/components/projects/project/overview/Activity/Activity.tsx` | ❌ Not Planned | Activity feed - Skipping per instructions |
|
||||
| ActivityCard | `/components/projects/project/overview/Activity/ActivityCard.tsx` | ❌ Not Planned | Activity item - Skipping per instructions |
|
||||
| AuctionCard | `/components/projects/project/overview/Activity/AuctionCard.tsx` | ✅ Completed | Auction display - Used in Overview page |
|
||||
| OverviewInfo | `/components/projects/project/overview/OverviewInfo.tsx` | ✅ Completed | Overview information - Used in Overview page |
|
||||
|
||||
### Deployment Components
|
||||
| Component | Current Path | Migration Status | Notes |
|
||||
|-----------|-------------|-------|-------|
|
||||
| DeploymentDetailsCard | `/components/projects/project/deployments/DeploymentDetailsCard.tsx` | ✅ Completed | Deployment details - Used in Deployments page |
|
||||
| DeploymentDialogBodyCard | `/components/projects/project/deployments/DeploymentDialogBodyCard.tsx` | ❌ Not Planned | Deployment dialog - Skipping per instructions |
|
||||
| DeploymentMenu | `/components/projects/project/deployments/DeploymentMenu.tsx` | ❌ Not Planned | Deployment actions menu - Skipping per instructions |
|
||||
| FilterForm | `/components/projects/project/deployments/FilterForm.tsx` | ✅ Completed | Deployment filtering - Used in Deployments page |
|
||||
|
||||
### Dialog Components
|
||||
| Component | Current Path | Migration Status | Notes |
|
||||
|-----------|-------------|-------|-------|
|
||||
| CancelDeploymentDialog | `/components/projects/Dialog/CancelDeploymentDialog.tsx` | ❌ Not Planned | Cancel deployment - Skipping per instructions |
|
||||
| ChangeStateToProductionDialog | `/components/projects/Dialog/ChangeStateToProductionDialog.tsx` | ❌ Not Planned | Change deployment state - Skipping per instructions |
|
||||
| DeleteDeploymentDialog | `/components/projects/Dialog/DeleteDeploymentDialog.tsx` | ❌ Not Planned | Delete deployment - Skipping per instructions |
|
||||
| DeleteDomainDialog | `/components/projects/Dialog/DeleteDomainDialog.tsx` | ❌ Not Planned | Delete domain - Skipping per instructions |
|
||||
| DeleteVariableDialog | `/components/projects/Dialog/DeleteVariableDialog.tsx` | ❌ Not Planned | Delete variable - Skipping per instructions |
|
||||
| DeleteWebhookDialog | `/components/projects/Dialog/DeleteWebhookDialog.tsx` | ❌ Not Planned | Delete webhook - Skipping per instructions |
|
||||
| DisconnectRepositoryDialog | `/components/projects/Dialog/DisconnectRepositoryDialog.tsx` | ❌ Not Planned | Disconnect repository - Skipping per instructions |
|
||||
| RemoveMemberDialog | `/components/projects/Dialog/RemoveMemberDialog.tsx` | ❌ Not Planned | Remove team member - Skipping per instructions |
|
||||
| TransferProjectDialog | `/components/projects/Dialog/TransferProjectDialog.tsx` | ❌ Not Planned | Transfer project ownership - Skipping per instructions |
|
||||
|
||||
### Project Creation Components
|
||||
| Component | Current Path | Migration Status | Notes |
|
||||
|-----------|-------------|-------|-------|
|
||||
| ApproveTransactionModal | `/components/projects/create/ApproveTransactionModal.tsx` | ❌ Not Planned | Transaction approval - Skipping per instructions |
|
||||
| CheckBalanceIframe | `/components/projects/create/CheckBalanceIframe.tsx` | ❌ Not Planned | Balance check - Skipping per instructions |
|
||||
| Configure | `/components/projects/create/Configure.tsx` | ❌ Not Planned | Project configuration - Skipping per instructions |
|
||||
| ConnectAccount | `/components/projects/create/ConnectAccount.tsx` | ❌ Not Planned | Account connection - Skipping per instructions |
|
||||
| ConnectAccountTabPanel | `/components/projects/create/ConnectAccountTabPanel.tsx` | ❌ Not Planned | Connection tab panel - Skipping per instructions |
|
||||
| Deploy | `/components/projects/create/Deploy.tsx` | ❌ Not Planned | Project deployment - Skipping per instructions |
|
||||
| DeployStep | `/components/projects/create/DeployStep.tsx` | ❌ Not Planned | Deployment step - Skipping per instructions |
|
||||
| MockConnectGitCard | `/components/projects/create/MockConnectGitCard.tsx` | ❌ Not Planned | Git connection mockup - Skipping per instructions |
|
||||
| ProjectRepoCard | `/components/projects/create/ProjectRepoCard/ProjectRepoCard.tsx` | ❌ Not Planned | Repository card - Skipping per instructions |
|
||||
| RepositoryList | `/components/projects/create/RepositoryList/RepositoryList.tsx` | ❌ Not Planned | Repository selection - Skipping per instructions |
|
||||
| TemplateCard | `/components/projects/create/TemplateCard/TemplateCard.tsx` | ❌ Not Planned | Template selection card - Skipping per instructions |
|
||||
|
||||
## 4. Loading Components
|
||||
| Component | Current Path | Migration Status | Notes |
|
||||
|-----------|-------------|-------|-------|
|
||||
| LoadingOverlay | `/components/loading/loading-overlay.tsx` | ❌ Not Planned | Loading state overlay - Skipping per instructions |
|
||||
|
||||
## 5. IFrame Components
|
||||
| Component | Current Path | Migration Status | Notes |
|
||||
|-----------|-------------|-------|-------|
|
||||
| AutoSignInIFrameModal | `/components/shared/auth/AutoSignInIFrameModal.tsx` | ✅ Completed | Auto sign-in modal - Consolidated with duplicate |
|
||||
| AutoSignInIFrameModal | `/components/wallet/AutoSignInIFrameModal.tsx` | ✅ Completed | Duplicate component consolidated with version from shared/auth |
|
||||
|
||||
## 6. Page Components (Used in Routes)
|
||||
|
||||
These components are used directly in routes and should be migrated as page components:
|
||||
|
||||
### Organization/Project Pages
|
||||
| Component | Current Path | Migration Status | Route Path |
|
||||
|-----------|-------------|-----------------|------------|
|
||||
| ProjectsScreen | `/pages/org-slug/ProjectsScreen.tsx` | ❌ Not Planned | `/:orgSlug` - Skipping per instructions |
|
||||
| Settings (Org) | `/pages/org-slug/Settings.tsx` | ❌ Not Planned | `/:orgSlug/settings` - Skipping per instructions |
|
||||
| Id (Project) | `/pages/org-slug/projects/Id.tsx` | ❌ Not Planned | `/:orgSlug/projects/:id` - Skipping per instructions |
|
||||
|
||||
### Project Tab Pages
|
||||
| Component | Current Path | Migration Status | Route Path |
|
||||
|-----------|-------------|-----------------|------------|
|
||||
| OverviewTabPanel | `/pages/org-slug/projects/id/Overview.tsx` | ✅ Completed | `/:orgSlug/projects/:id` (index) |
|
||||
| DeploymentsTabPanel | `/pages/org-slug/projects/id/Deployments.tsx` | ✅ Completed | `/:orgSlug/projects/:id/deployments` |
|
||||
| SettingsTabPanel | `/pages/org-slug/projects/id/Settings.tsx` | ❌ Not Started | `/:orgSlug/projects/:id/settings` |
|
||||
|
||||
### Project Settings Pages
|
||||
| Component | Current Path | Route Path |
|
||||
|-----------|-------------|------------|
|
||||
| GeneralTabPanel | `/pages/org-slug/projects/id/settings/General.tsx` | `/:orgSlug/projects/:id/settings` (index) |
|
||||
| Domains | `/pages/org-slug/projects/id/settings/Domains.tsx` | `/:orgSlug/projects/:id/settings/domains` |
|
||||
| GitTabPanel | `/pages/org-slug/projects/id/settings/Git.tsx` | `/:orgSlug/projects/:id/settings/git` |
|
||||
| EnvironmentVariablesTabPanel | `/pages/org-slug/projects/id/settings/EnvironmentVariables.tsx` | `/:orgSlug/projects/:id/settings/environment-variables` |
|
||||
| CollaboratorsTabPanel | `/pages/org-slug/projects/id/settings/Collaborators.tsx` | `/:orgSlug/projects/:id/settings/collaborators` |
|
||||
| AddDomain | `/pages/org-slug/projects/id/settings/domains/add/index.tsx` | `/:orgSlug/projects/:id/settings/domains/add` |
|
||||
| Config (Domain) | `/pages/org-slug/projects/id/settings/domains/add/Config.tsx` | `/:orgSlug/projects/:id/settings/domains/add/config` |
|
||||
|
||||
### Project Creation Pages
|
||||
| Component | Current Path | Route Path |
|
||||
|-----------|-------------|------------|
|
||||
| CreateProjectLayout | `/pages/org-slug/projects/create/CreateProjectLayout.tsx` | `/:orgSlug/projects/create` |
|
||||
| NewProject | `/pages/org-slug/projects/create/NewProject.tsx` | `/:orgSlug/projects/create` (index) |
|
||||
| CreateWithTemplate | `/pages/org-slug/projects/create/Template.tsx` | `/:orgSlug/projects/create/template` |
|
||||
| Configure (Projects) | `/components/projects/create/Configure.tsx` | `/:orgSlug/projects/create/configure` |
|
||||
| Deploy (Projects) | `/components/projects/create/Deploy.tsx` | `/:orgSlug/projects/create/deploy` |
|
||||
| Id (Success) | `/pages/org-slug/projects/create/success/Id.tsx` | `/:orgSlug/projects/create/success/:id` |
|
||||
|
||||
### Template Pages
|
||||
| Component | Current Path | Route Path |
|
||||
|-----------|-------------|------------|
|
||||
| CreateRepo | `/pages/org-slug/projects/create/template/index.tsx` | `/:orgSlug/projects/create/template` (index) |
|
||||
| Configure (Template) | `/pages/org-slug/projects/create/template/Configure.tsx` | `/:orgSlug/projects/create/template/configure` |
|
||||
| Deploy (Template) | `/pages/org-slug/projects/create/template/Deploy.tsx` | `/:orgSlug/projects/create/template/deploy` |
|
||||
|
||||
### Auth and Onboarding Pages
|
||||
| Component | Current Path | Route Path |
|
||||
|-----------|-------------|------------|
|
||||
| Index | `/pages/index.tsx` | `/` |
|
||||
| AuthPage | `/pages/AuthPage.tsx` | `/login` |
|
||||
| BuyPrepaidService | `/pages/BuyPrepaidService.tsx` | `/buy-prepaid-service` |
|
||||
| OnboardingPage | `/pages/OnboardingPage.tsx` | `/onboarding` |
|
||||
| OnboardingDemoPage | `/pages/OnboardingDemoPage.tsx` | `/onboarding-demo` |
|
||||
|
||||
### Layouts
|
||||
| Component | Current Path | Route Path |
|
||||
|-----------|-------------|------------|
|
||||
| RootLayout | `/layouts/RootLayout.tsx` | Root layout for all routes |
|
||||
| DashboardLayout | `/layouts/DashboardLayout.tsx` | Layout for /:orgSlug routes |
|
||||
| ProjectSearchLayout | `/layouts/ProjectSearch.tsx` | Layout for project search functionality |
|
||||
|
||||
## Notes and Observations
|
||||
|
||||
1. **Duplicated Components**:
|
||||
- `ProjectSearchBar`: Appears in both `/components/layout/search/ProjectSearchBar/` and `/components/projects/ProjectSearchBar/`
|
||||
|
||||
## Migration Progress Summary
|
||||
|
||||
### Completed Migrations
|
||||
1. **Core Components**: 7/7 components (100% complete)
|
||||
2. **Layout Feature - Navigation Components**: 4/4 components (100% complete)
|
||||
3. **Project Tab Pages**: 2/3 components (67% complete)
|
||||
- Migrated: OverviewTabPanel, DeploymentsTabPanel
|
||||
- Pending: SettingsTabPanel
|
||||
4. **Project Overview Components**: 2/4 components (50% complete)
|
||||
- Migrated: AuctionCard, OverviewInfo
|
||||
- Not Planned: Activity, ActivityCard
|
||||
5. **Deployment Components**: 2/4 components (50% complete)
|
||||
- Migrated: DeploymentDetailsCard, FilterForm
|
||||
- Not Planned: DeploymentDialogBodyCard, DeploymentMenu
|
||||
6. **IFrame Components**: 2/2 components (100% complete)
|
||||
|
||||
### Next Steps
|
||||
1. Migrate the SettingsTabPanel and related settings pages
|
||||
2. Migrate the Project Creation pages
|
||||
3. Migrate the Template pages
|
||||
|
||||
### Migration Notes
|
||||
- The migrated components have been adapted to work with Next.js App Router
|
||||
- Many UI components and utilities were already available in the codebase
|
||||
- Type definitions have been updated to ensure type safety
|
||||
- Redundant files have been cleaned up
|
||||
@@ -0,0 +1,171 @@
|
||||
# Next.js App Router Structure with Abbreviated URLs
|
||||
|
||||
```
|
||||
app/
|
||||
page.tsx # URL: /
|
||||
layout.tsx
|
||||
not-found.tsx
|
||||
global-error.tsx
|
||||
|
||||
login/
|
||||
page.tsx # URL: /login
|
||||
|
||||
wallet/
|
||||
page.tsx # URL: /wallet
|
||||
layout.tsx
|
||||
|
||||
store/
|
||||
page.tsx # URL: /store
|
||||
layout.tsx
|
||||
|
||||
(web3-authenticated)/ # Auth wrapper (not in URL)
|
||||
layout.tsx
|
||||
|
||||
(dashboard)/ # Dashboard wrapper (not in URL)
|
||||
layout.tsx
|
||||
|
||||
page.tsx # URL: /
|
||||
|
||||
(buy-prepaid-service)/
|
||||
bp/ # Abbreviated
|
||||
page.tsx # URL: /bp
|
||||
|
||||
(projects)/
|
||||
pr/ # Abbreviated
|
||||
page.tsx # URL: /pr
|
||||
|
||||
[provider]/
|
||||
page.tsx # URL: /pr/[provider]
|
||||
|
||||
[orgSlug]/
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]
|
||||
layout.tsx
|
||||
error.tsx
|
||||
not-found.tsx
|
||||
loading.tsx
|
||||
|
||||
(settings)/
|
||||
set/ # Abbreviated
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/set
|
||||
|
||||
(projects)/
|
||||
ps/ # Abbreviated
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps
|
||||
layout.tsx
|
||||
loading.tsx
|
||||
error.tsx
|
||||
|
||||
(create)/
|
||||
cr/ # Abbreviated
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps/cr
|
||||
layout.tsx
|
||||
|
||||
(configure)/
|
||||
cf/ # Abbreviated
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps/cr/cf
|
||||
|
||||
(deploy)/
|
||||
dp/ # Abbreviated
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps/cr/dp
|
||||
loading.tsx
|
||||
|
||||
(success)/
|
||||
sc/ # Abbreviated
|
||||
[id]/
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps/cr/sc/[id]
|
||||
|
||||
(template)/
|
||||
tm/ # Abbreviated
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps/cr/tm
|
||||
|
||||
(configure)/
|
||||
cf/ # Abbreviated
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps/cr/tm/cf
|
||||
|
||||
(deploy)/
|
||||
dp/ # Abbreviated
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps/cr/tm/dp
|
||||
loading.tsx
|
||||
|
||||
[id]/
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps/[id]
|
||||
layout.tsx
|
||||
loading.tsx
|
||||
error.tsx
|
||||
not-found.tsx
|
||||
|
||||
(deployments)/
|
||||
dep/ # Abbreviated
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps/[id]/dep
|
||||
loading.tsx
|
||||
|
||||
(integrations)/
|
||||
int/ # Abbreviated
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps/[id]/int
|
||||
|
||||
(settings)/
|
||||
set/ # Abbreviated
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps/[id]/set
|
||||
layout.tsx
|
||||
|
||||
(domains)/
|
||||
dom/ # Abbreviated
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps/[id]/set/dom
|
||||
|
||||
(add)/
|
||||
add/ # Kept as-is (short enough)
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps/[id]/set/dom/add
|
||||
|
||||
(config)/
|
||||
cf/ # Abbreviated
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps/[id]/set/dom/add/cf
|
||||
|
||||
(git)/
|
||||
git/ # Kept as-is (short enough)
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps/[id]/set/git
|
||||
|
||||
(environment-variables)/
|
||||
env/ # Abbreviated
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps/[id]/set/env
|
||||
|
||||
(collaborators)/
|
||||
col/ # Abbreviated
|
||||
page.tsx # URL: /pr/[provider]/[orgSlug]/ps/[id]/set/col
|
||||
```
|
||||
|
||||
## Abbreviation Legend
|
||||
|
||||
- bp = buy-prepaid-service
|
||||
- pr = projects
|
||||
- ps = projects (within organization)
|
||||
- cr = create
|
||||
- cf = configure
|
||||
- dp = deploy
|
||||
- sc = success
|
||||
- tm = template
|
||||
- dep = deployments
|
||||
- int = integrations
|
||||
- set = settings
|
||||
- dom = domains
|
||||
- env = environment-variables
|
||||
- col = collaborators
|
||||
|
||||
## API Routes
|
||||
|
||||
```
|
||||
app/
|
||||
api/
|
||||
route.ts
|
||||
|
||||
organizations/
|
||||
[slug]/
|
||||
route.ts
|
||||
|
||||
projects/
|
||||
route.ts
|
||||
|
||||
[id]/
|
||||
route.ts
|
||||
deployments/
|
||||
route.ts
|
||||
```
|
||||
@@ -0,0 +1,441 @@
|
||||
# Next.js App Router File Templates
|
||||
|
||||
This document provides basic templates for the common file types used in a Next.js application with the App Router. These templates follow the current best practices for Next.js 15.
|
||||
|
||||
## Page Templates
|
||||
|
||||
### Basic Page (`page.tsx`)
|
||||
|
||||
```tsx
|
||||
import { Metadata } from 'next'
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: 'Page Title',
|
||||
description: 'Page description',
|
||||
}
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<div>
|
||||
<h1>Page Content</h1>
|
||||
{/* Page content goes here */}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Dynamic Route Page (`[slug]/page.tsx`)
|
||||
|
||||
```tsx
|
||||
export async function generateMetadata({ params }) {
|
||||
return {
|
||||
title: `Page for ${params.slug}`,
|
||||
description: `Description for ${params.slug}`,
|
||||
}
|
||||
}
|
||||
|
||||
export default function DynamicPage({ params }) {
|
||||
const { slug } = params
|
||||
|
||||
return (
|
||||
<div>
|
||||
<h1>Dynamic Page: {slug}</h1>
|
||||
{/* Dynamic page content goes here */}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Layout Templates
|
||||
|
||||
### Root Layout (`layout.tsx`)
|
||||
|
||||
```tsx
|
||||
import { Metadata } from 'next'
|
||||
import './globals.css'
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: {
|
||||
template: '%s | Site Name',
|
||||
default: 'Site Name',
|
||||
},
|
||||
description: 'Site description',
|
||||
}
|
||||
|
||||
export default function RootLayout({ children }) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<body>
|
||||
<header>
|
||||
{/* Header content */}
|
||||
</header>
|
||||
<main>{children}</main>
|
||||
<footer>
|
||||
{/* Footer content */}
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Nested Layout (`(dashboard)/layout.tsx`)
|
||||
|
||||
```tsx
|
||||
export default function DashboardLayout({ children }) {
|
||||
return (
|
||||
<div className="dashboard-layout">
|
||||
<nav className="dashboard-nav">
|
||||
{/* Dashboard navigation */}
|
||||
</nav>
|
||||
<div className="dashboard-content">
|
||||
{children}
|
||||
</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Auth Layout with Session Check (`(authenticated)/layout.tsx`)
|
||||
|
||||
```tsx
|
||||
import { redirect } from 'next/navigation'
|
||||
|
||||
// This is a Server Component
|
||||
export default async function AuthLayout({ children }) {
|
||||
const session = await getSession() // Replace with your auth solution
|
||||
|
||||
if (!session) {
|
||||
redirect('/login')
|
||||
}
|
||||
|
||||
return <>{children}</>
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling Templates
|
||||
|
||||
### Not Found (`not-found.tsx`)
|
||||
|
||||
```tsx
|
||||
import Link from 'next/link'
|
||||
|
||||
export const metadata = {
|
||||
title: 'Not Found',
|
||||
description: 'Page not found',
|
||||
}
|
||||
|
||||
export default function NotFound() {
|
||||
return (
|
||||
<div className="error-container">
|
||||
<h1>404 - Page Not Found</h1>
|
||||
<p>The page you are looking for does not exist.</p>
|
||||
<Link href="/">
|
||||
Return to Home
|
||||
</Link>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Error Page (`error.tsx`)
|
||||
|
||||
```tsx
|
||||
'use client' // Error components must be Client Components
|
||||
|
||||
import { useEffect } from 'react'
|
||||
|
||||
export default function Error({ error, reset }) {
|
||||
useEffect(() => {
|
||||
// Log the error to an error reporting service
|
||||
console.error(error)
|
||||
}, [error])
|
||||
|
||||
return (
|
||||
<div className="error-container">
|
||||
<h2>Something went wrong!</h2>
|
||||
<button
|
||||
onClick={
|
||||
// Attempt to recover by trying to re-render the segment
|
||||
() => reset()
|
||||
}
|
||||
>
|
||||
Try again
|
||||
</button>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Global Error (`global-error.tsx`)
|
||||
|
||||
```tsx
|
||||
'use client'
|
||||
|
||||
export default function GlobalError({ error, reset }) {
|
||||
return (
|
||||
<html>
|
||||
<body>
|
||||
<div className="global-error">
|
||||
<h2>Something went wrong!</h2>
|
||||
<button onClick={() => reset()}>Try again</button>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Loading States
|
||||
|
||||
### Loading Component (`loading.tsx`)
|
||||
|
||||
```tsx
|
||||
export default function Loading() {
|
||||
return (
|
||||
<div className="loading-container">
|
||||
<div className="loading-spinner"></div>
|
||||
<p>Loading...</p>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Route Handlers
|
||||
|
||||
### API Route (`api/route.ts`)
|
||||
|
||||
```ts
|
||||
import { NextResponse } from 'next/server'
|
||||
|
||||
export async function GET(request) {
|
||||
// Handle GET request
|
||||
return NextResponse.json({ message: 'Hello World' })
|
||||
}
|
||||
|
||||
export async function POST(request) {
|
||||
// Handle POST request
|
||||
const body = await request.json()
|
||||
return NextResponse.json({ received: body })
|
||||
}
|
||||
```
|
||||
|
||||
### Dynamic API Route (`api/[slug]/route.ts`)
|
||||
|
||||
```ts
|
||||
import { NextResponse } from 'next/server'
|
||||
|
||||
export async function GET(request, { params }) {
|
||||
const { slug } = params
|
||||
return NextResponse.json({ slug })
|
||||
}
|
||||
```
|
||||
|
||||
## Middleware
|
||||
|
||||
### Middleware (`middleware.ts`)
|
||||
|
||||
Place this file in the root of your project:
|
||||
|
||||
```ts
|
||||
import { NextResponse } from 'next/server'
|
||||
import type { NextRequest } from 'next/server'
|
||||
|
||||
// This function runs before requests are completed
|
||||
export function middleware(request: NextRequest) {
|
||||
const currentUrl = request.nextUrl.clone()
|
||||
|
||||
// Example: check if user is authenticated
|
||||
const isAuthenticated = checkAuth(request)
|
||||
|
||||
if (!isAuthenticated && currentUrl.pathname.startsWith('/protected')) {
|
||||
return NextResponse.redirect(new URL('/login', request.url))
|
||||
}
|
||||
|
||||
return NextResponse.next()
|
||||
}
|
||||
|
||||
// Configure matcher for paths that should trigger middleware
|
||||
export const config = {
|
||||
matcher: ['/protected/:path*', '/api/:path*'],
|
||||
}
|
||||
|
||||
// Example auth check function
|
||||
function checkAuth(request) {
|
||||
// Implement your auth check logic here
|
||||
return !!request.cookies.get('auth-token')
|
||||
}
|
||||
```
|
||||
|
||||
## Utilities - Server Actions
|
||||
|
||||
### Form Actions (`actions.ts`)
|
||||
|
||||
```ts
|
||||
'use server'
|
||||
|
||||
export async function submitForm(formData: FormData) {
|
||||
// Validate data
|
||||
const name = formData.get('name')
|
||||
const email = formData.get('email')
|
||||
|
||||
// Process data
|
||||
try {
|
||||
// Save to database or send to API
|
||||
await saveToDatabase({ name, email })
|
||||
return { success: true }
|
||||
} catch (error) {
|
||||
return { success: false, error: error.message }
|
||||
}
|
||||
}
|
||||
|
||||
async function saveToDatabase(data) {
|
||||
// Implementation for database interaction
|
||||
}
|
||||
```
|
||||
|
||||
## Server Component with Data Fetching
|
||||
|
||||
### Data Fetching in Server Component (`dashboard/page.tsx`)
|
||||
|
||||
```tsx
|
||||
// This is a Server Component
|
||||
export default async function DashboardPage() {
|
||||
// This data fetching happens on the server
|
||||
const data = await fetchDashboardData()
|
||||
|
||||
return (
|
||||
<div>
|
||||
<h1>Dashboard</h1>
|
||||
<div className="dashboard-stats">
|
||||
{data.map(item => (
|
||||
<div key={item.id} className="stat-card">
|
||||
<h3>{item.title}</h3>
|
||||
<p>{item.value}</p>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
async function fetchDashboardData() {
|
||||
// API or database call
|
||||
const res = await fetch('https://api.example.com/dashboard-data', {
|
||||
cache: 'no-store' // Don't cache this data
|
||||
})
|
||||
|
||||
if (!res.ok) {
|
||||
throw new Error('Failed to fetch dashboard data')
|
||||
}
|
||||
|
||||
return res.json()
|
||||
}
|
||||
```
|
||||
|
||||
## Client Component with Hooks
|
||||
|
||||
### Interactive Client Component (`components/Counter.tsx`)
|
||||
|
||||
```tsx
|
||||
'use client' // Mark as Client Component
|
||||
|
||||
import { useState } from 'react'
|
||||
|
||||
export default function Counter() {
|
||||
const [count, setCount] = useState(0)
|
||||
|
||||
return (
|
||||
<div>
|
||||
<p>Count: {count}</p>
|
||||
<button onClick={() => setCount(count + 1)}>
|
||||
Increment
|
||||
</button>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Parallel Routes
|
||||
|
||||
### Parallel Route Layout (`@dashboard/page.tsx` and `@profile/page.tsx`)
|
||||
|
||||
In your directory structure:
|
||||
```
|
||||
app/
|
||||
layout.tsx
|
||||
[user]/
|
||||
layout.tsx
|
||||
page.tsx
|
||||
@dashboard/
|
||||
page.tsx
|
||||
@profile/
|
||||
page.tsx
|
||||
```
|
||||
|
||||
In `[user]/layout.tsx`:
|
||||
```tsx
|
||||
export default function UserLayout({ children, dashboard, profile }) {
|
||||
return (
|
||||
<div className="user-page">
|
||||
<div className="sidebar">
|
||||
{/* Sidebar navigation */}
|
||||
</div>
|
||||
<div className="main-content">
|
||||
{children}
|
||||
</div>
|
||||
<div className="dashboard-slot">
|
||||
{dashboard}
|
||||
</div>
|
||||
<div className="profile-slot">
|
||||
{profile}
|
||||
</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Route Interception
|
||||
|
||||
### Photo Modal Example (`./(.)photos/[id]/page.tsx`)
|
||||
|
||||
The directory structure might look like:
|
||||
```
|
||||
app/
|
||||
photos/
|
||||
page.tsx
|
||||
[id]/
|
||||
page.tsx
|
||||
(.)photos/
|
||||
[id]/
|
||||
page.tsx // This intercepts /photos/[id]
|
||||
```
|
||||
|
||||
In `./(.)photos/[id]/page.tsx`:
|
||||
```tsx
|
||||
export default function PhotoModal({ params }) {
|
||||
const { id } = params
|
||||
|
||||
// Fetch photo data based on id
|
||||
|
||||
return (
|
||||
<div className="modal">
|
||||
<div className="modal-content">
|
||||
<h2>Photo {id}</h2>
|
||||
<img src={`/api/photos/${id}`} alt={`Photo ${id}`} />
|
||||
</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [Official Next.js Documentation](https://nextjs.org/docs/app)
|
||||
- [Pages and Layouts](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts)
|
||||
- [Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers)
|
||||
- [Error Handling](https://nextjs.org/docs/app/building-your-application/routing/error-handling)
|
||||
- [Loading UI and Streaming](https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming)
|
||||
- [Metadata API](https://nextjs.org/docs/app/building-your-application/optimizing/metadata)
|
||||
- [Server Actions](https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions)
|
||||
- [Middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware)
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,215 @@
|
||||
# Comprehensive Technology Documentation & GitHub Links (March 2025)
|
||||
|
||||
*Last updated: March 3, 2025*
|
||||
|
||||
## Core Toolchain
|
||||
|
||||
| Technology | Current Version | Documentation | GitHub Repository |
|
||||
|------------|----------------|---------------|-------------------|
|
||||
| **Turborepo** | 2.4.0 | [turbo.build/repo](https://turbo.build/repo) | [vercel/turborepo](https://github.com/vercel/turborepo) |
|
||||
| **Next.js 15 App Router** | 15.0.0 | [nextjs.org/docs/app](https://nextjs.org/docs/app) | [vercel/next.js](https://github.com/vercel/next.js) |
|
||||
| **Biome** | 2.0.0 | [biomejs.dev](https://biomejs.dev) | [biomejs/biome](https://github.com/biomejs/biome) |
|
||||
| **PNPM** | 10.5.2 | [pnpm.io](https://pnpm.io) | [pnpm/pnpm](https://github.com/pnpm/pnpm) |
|
||||
|
||||
## Styling & UI
|
||||
|
||||
| Technology | Current Version | Documentation | GitHub Repository |
|
||||
|------------|----------------|---------------|-------------------|
|
||||
| **Tailwind CSS v4** | 4.0.0 | [tailwindcss.com/docs/v4](https://tailwindcss.com/docs/v4) | [tailwindlabs/tailwindcss](https://github.com/tailwindlabs/tailwindcss) |
|
||||
| **ShadCN UI** | 2.0.0 | [ui.shadcn.com](https://ui.shadcn.com/docs) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
|
||||
| **Radix UI** | 3.0.0 | [radix-ui.com](https://radix-ui.com) | [radix-ui/primitives](https://github.com/radix-ui/primitives) |
|
||||
| **Lucide** (icons library) | 1.0.0 | [lucide.dev](https://lucide.dev) | [lucide-icons/lucide](https://github.com/lucide-icons/lucide) |
|
||||
| **Sonner** | 2.1.0 | [sonner.dev](https://sonner.dev) | [sonnerjs/sonner](https://github.com/sonnerjs/sonner) |
|
||||
|
||||
## Language & Validation
|
||||
|
||||
| Technology | Current Version | Documentation | GitHub Repository |
|
||||
|------------|----------------|---------------|-------------------|
|
||||
| **TypeScript** | 6.0.0 | [typescriptlang.org/docs](https://www.typescriptlang.org/docs) | [microsoft/TypeScript](https://github.com/microsoft/TypeScript) |
|
||||
| **Zod** | 4.0.0 | [zod.dev](https://zod.dev) | [colinhacks/zod](https://github.com/colinhacks/zod) |
|
||||
|
||||
## React Ecosystem
|
||||
|
||||
| Technology | Current Version | Documentation | GitHub Repository |
|
||||
|------------|----------------|---------------|-------------------|
|
||||
| **React** | 19.2.0 | [react.dev](https://react.dev) | [facebook/react](https://github.com/facebook/react) |
|
||||
| **React Hook Form** | 9.0.0 | [react-hook-form.com](https://react-hook-form.com) | [react-hook-form/react-hook-form](https://github.com/react-hook-form/react-hook-form) |
|
||||
| **React OAuth Popup** | 3.0.1 | [react-oauth-popup.dev](https://react-oauth-popup.dev) | [react-oauth/popup](https://github.com/react-oauth/popup) |
|
||||
| **React Testing Library** | 15.0.0 | [testing-library.com/react](https://testing-library.com/react) | [testing-library/react-testing-library](https://github.com/testing-library/react-testing-library) |
|
||||
|
||||
## Data & Utilities
|
||||
|
||||
| Technology | Current Version | Documentation | GitHub Repository |
|
||||
|------------|----------------|---------------|-------------------|
|
||||
| **GraphQL** | June 2021 Specification | [graphql.org](https://graphql.org) | [graphql/graphql-spec](https://github.com/graphql/graphql-spec) |
|
||||
| **Axios** | 1.8.1 | [axios-http.com/docs](https://axios-http.com/docs) | [axios/axios](https://github.com/axios/axios) |
|
||||
| **Date-FNS** | 4.1.0 | [date-fns.org](https://date-fns.org) | [date-fns/date-fns](https://github.com/date-fns/date-fns) |
|
||||
| **Recharts** | 3.0.0 | [recharts.org](https://recharts.org) | [recharts/recharts](https://github.com/recharts/recharts) |
|
||||
| **UUID** | 9.0.1 | [uuid.dev](https://uuid.dev) | [uuidjs/uuid](https://github.com/uuidjs/uuid) |
|
||||
|
||||
## Testing & Development Tools
|
||||
|
||||
| Technology | Current Version | Documentation | GitHub Repository |
|
||||
|------------|----------------|---------------|-------------------|
|
||||
| **Vitest** | 2.0.0 | [vitest.dev](https://vitest.dev) | [vitest-dev/vitest](https://github.com/vitest-dev/vitest) |
|
||||
| **Jest** | 30.0.0 | [jestjs.io](https://jestjs.io) | [jestjs/jest](https://github.com/jestjs/jest) |
|
||||
| **Playwright** | 1.45.0 | [playwright.dev](https://playwright.dev) | [microsoft/playwright](https://github.com/microsoft/playwright) |
|
||||
| **Cypress** | 13.6.0 | [cypress.io](https://www.cypress.io) | [cypress-io/cypress](https://github.com/cypress-io/cypress) |
|
||||
| **Storybook** | 8.0.0 | [storybook.js.org](https://storybook.js.org) | [storybookjs/storybook](https://github.com/storybookjs/storybook) |
|
||||
| **Left Hook** | 0.9.4 | [lefthook.dev](https://lefthook.dev) | [evilmartians/lefthook](https://github.com/evilmartians/lefthook) |
|
||||
| **GitHub** | N/A (Platform) | [docs.github.com](https://docs.github.com) | N/A |
|
||||
| **Gitea** | 2.5.0 | [docs.gitea.com](https://docs.gitea.com) | [go-gitea/gitea](https://github.com/go-gitea/gitea) |
|
||||
| **Octokit** | 8.0.0 | [octokit.github.io](https://octokit.github.io/rest.js/) | [octokit/rest.js](https://github.com/octokit/rest.js) |
|
||||
|
||||
## Web3 & Authentication
|
||||
|
||||
| Technology | Current Version | Documentation | GitHub Repository |
|
||||
|------------|----------------|---------------|-------------------|
|
||||
| **Web3Modal** | 3.0.0 | [web3modal.com](https://web3modal.com) | [WalletConnect/web3modal](https://github.com/WalletConnect/web3modal) |
|
||||
| **SIWE** (Sign-In with Ethereum) | 2.0.0 | [login.xyz](https://login.xyz) | [spruceid/siwe](https://github.com/spruceid/siwe) |
|
||||
| **Reown Wallet Kit** | 3.0.0 | [walletconnect.com](https://walletconnect.com) | [WalletConnect/walletconnect-monorepo](https://github.com/WalletConnect/walletconnect-monorepo) |
|
||||
| **Clerk** | 5.0.0 | [clerk.com/docs](https://clerk.com/docs) | [clerkinc/javascript](https://github.com/clerkinc/javascript) |
|
||||
|
||||
## Laconic Network & Infrastructure
|
||||
|
||||
| Technology | Current Version | Documentation | GitHub Repository |
|
||||
|------------|----------------|---------------|-------------------|
|
||||
| **Laconic Network** | 2.1.0 | [laconic.com/docs](https://laconic.com/docs) | [laconic-network](https://github.com/laconic-network) |
|
||||
| **Laconic.com** | N/A | [laconic.com](https://laconic.com) | [laconic-network/portal](https://github.com/laconic-network/portal) |
|
||||
| **Laconic Web Wallet** | 1.4.0 | [wallet.laconic.com](https://wallet.laconic.com) | [laconic-network/wallet](https://github.com/laconic-network/wallet) |
|
||||
|
||||
## Additional Web3 Tools for React
|
||||
|
||||
| Technology | Current Version | Purpose | Documentation | GitHub Repository |
|
||||
|------------|----------------|---------|---------------|-------------------|
|
||||
| **Wagmi** | 2.0.0 | Ethereum Hooks | [wagmi.sh](https://wagmi.sh) | [wagmi-dev/wagmi](https://github.com/wagmi-dev/wagmi) |
|
||||
| **The Graph** | 2.1.0 | Blockchain Indexing | [thegraph.com/docs](https://thegraph.com/docs) | [graphprotocol/graph-node](https://github.com/graphprotocol/graph-node) |
|
||||
| **Hardhat** | 3.0.0 | Smart Contract Development | [hardhat.org](https://hardhat.org) | [NomicFoundation/hardhat](https://github.com/NomicFoundation/hardhat) |
|
||||
| **IPFS** | 0.28.0 | Decentralized Storage | [docs.ipfs.tech](https://docs.ipfs.tech) | [ipfs/js-ipfs](https://github.com/ipfs/js-ipfs) |
|
||||
| **Viem** | 2.0.0 | Ethereum Interface | [viem.sh](https://viem.sh) | [wagmi-dev/viem](https://github.com/wagmi-dev/viem) |
|
||||
| **Ethers.js** | 6.1.0 | Ethereum Library | [docs.ethers.org](https://docs.ethers.org) | [ethers-io/ethers.js](https://github.com/ethers-io/ethers.js) |
|
||||
|
||||
## React 19 Key Features (New in 2025)
|
||||
|
||||
React 19, released in December 2024, includes several major improvements:
|
||||
|
||||
1. **React Server Components (RSC)**: Now fully integrated in the stable release
|
||||
2. **Actions**: Simplifies data fetching and state updates, especially for forms
|
||||
3. **Document Metadata**: Built-in support for managing document metadata (titles, descriptions, meta tags)
|
||||
4. **Concurrent Rendering**: Improved performance for complex UI updates
|
||||
5. **Enhanced Hooks**: New hooks and improvements to existing ones
|
||||
6. **Performance Optimization**: Significant improvements in rendering speed and memory usage
|
||||
7. **Better Developer Experience**: Improved error messages and debugging tools
|
||||
|
||||
## Migration Notes
|
||||
|
||||
When upgrading between major versions, consider these important points:
|
||||
|
||||
1. **Turborepo 2.x to 3.x**: Expected in late 2025, will likely focus on improved remote caching and better integration with CI/CD pipelines
|
||||
2. **Next.js 15 to 16**: Will likely focus on enhanced server components and improved data fetching patterns
|
||||
3. **Tailwind CSS 4 to 5**: May introduce new utility classes and performance optimizations
|
||||
4. **React 19 to 20**: Will continue the focus on concurrent rendering and server components
|
||||
5. **Testing Framework Migrations**:
|
||||
- **Jest to Vitest**: Use the compatibility mode for easier migration, then leverage Vitest's faster performance
|
||||
- **Cypress to Playwright**: Consider migrating for better parallel test execution and multi-browser support
|
||||
|
||||
## Best Practices for 2025
|
||||
|
||||
1. **Adopt Server Components**: Leverage React Server Components for improved performance and reduced client-side JavaScript
|
||||
2. **Embrace Type Safety**: Use TypeScript and Zod together for end-to-end type safety
|
||||
3. **Component Libraries**: Consider using ShadCN UI with Tailwind CSS for rapid UI development
|
||||
4. **Monorepo Structure**: Use Turborepo and PNPM for efficient management of monorepos
|
||||
5. **Testing Strategy**: Implement comprehensive testing with a layered approach:
|
||||
- **Unit Testing**: Vitest (faster than Jest, better ESM support) or Jest
|
||||
- **Component Testing**: React Testing Library with either Vitest or Jest
|
||||
- **E2E Testing**: Playwright (recommended for Next.js 15) or Cypress
|
||||
|
||||
## Future Trends (2025-2026)
|
||||
|
||||
1. **AI Integration**: More tools integrating AI capabilities for code generation and optimization
|
||||
2. **Edge Computing**: Increased focus on edge rendering and computing
|
||||
3. **Web3 Mainstream Adoption**: Simplified Web3 integration in traditional applications
|
||||
4. **Zero-Bundle Size**: Components that ship no JavaScript to the client
|
||||
5. **Hybrid Rendering Strategies**: Combination of static, server, and client rendering based on content type
|
||||
6. **Automated Testing**: Increased adoption of AI-assisted test generation and maintenance
|
||||
7. **Visual Testing**: Growing importance of visual regression testing in the UI development workflow
|
||||
|
||||
## Next.js 15 Testing Setup Guide
|
||||
|
||||
Setting up a robust testing environment for Next.js 15 applications involves configuring multiple testing tools for different layers of your application:
|
||||
|
||||
### 1. Unit and Component Testing
|
||||
|
||||
Choose between Vitest (recommended) or Jest:
|
||||
|
||||
```bash
|
||||
# For Vitest (faster, better ESM support)
|
||||
npm install -D vitest @testing-library/react @testing-library/jest-dom happy-dom
|
||||
|
||||
# For Jest
|
||||
npm install -D jest @testing-library/react @testing-library/jest-dom jest-environment-jsdom
|
||||
```
|
||||
|
||||
### 2. End-to-End Testing with Playwright (Recommended for Next.js 15)
|
||||
|
||||
```bash
|
||||
# Install Playwright
|
||||
npm init playwright@latest
|
||||
|
||||
# Or with specific browsers
|
||||
npx playwright install --with-deps chromium firefox webkit
|
||||
```
|
||||
|
||||
**Example Next.js 15 Playwright Test:**
|
||||
|
||||
```typescript
|
||||
// e2e/example.spec.ts
|
||||
import { test, expect } from '@playwright/test';
|
||||
|
||||
test('homepage has the correct title', async ({ page }) => {
|
||||
await page.goto('/');
|
||||
await expect(page).toHaveTitle(/My Next.js App/);
|
||||
});
|
||||
|
||||
test('navigation works correctly', async ({ page }) => {
|
||||
await page.goto('/');
|
||||
await page.click('text=About');
|
||||
await expect(page).toHaveURL(/.*about/);
|
||||
});
|
||||
```
|
||||
|
||||
### 3. Playwright Configuration for Next.js 15
|
||||
|
||||
```typescript
|
||||
// playwright.config.ts
|
||||
import { defineConfig } from '@playwright/test';
|
||||
|
||||
export default defineConfig({
|
||||
testDir: './e2e',
|
||||
webServer: {
|
||||
command: 'npm run dev',
|
||||
url: 'http://localhost:3000',
|
||||
reuseExistingServer: !process.env.CI,
|
||||
},
|
||||
use: {
|
||||
baseURL: 'http://localhost:3000',
|
||||
trace: 'on-first-retry',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### 4. Adding Scripts to package.json
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"test": "vitest", // or "jest"
|
||||
"test:e2e": "playwright test",
|
||||
"test:e2e:ui": "playwright test --ui"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*This documentation is current as of March 2025. Version numbers and links are subject to change as technologies evolve.*
|
||||
@@ -0,0 +1,525 @@
|
||||
# Component Documentation Standards
|
||||
|
||||
This document outlines the documentation standards for components across the entire project.
|
||||
Following these standards ensures consistency and makes the codebase more maintainable.
|
||||
|
||||
## TypeScript Documentation Approach
|
||||
|
||||
This project uses a **TypeScript-first** documentation approach, focusing on TypeScript's native
|
||||
documentation capabilities rather than traditional JSDoc. While TypeScript supports JSDoc syntax, we
|
||||
prioritize TypeScript-specific documentation patterns where possible.
|
||||
|
||||
### TSDoc vs JSDoc
|
||||
|
||||
- **TSDoc** is a documentation standard specifically designed for TypeScript
|
||||
- We prefer TypeScript's native type annotations over JSDoc type annotations
|
||||
- Use explicit type definitions in code instead of JSDoc type comments when possible
|
||||
- When JSDoc-style comments are needed, use TypeScript-compatible JSDoc tags
|
||||
|
||||
### Documentation Tools
|
||||
|
||||
Our documentation approach is designed to work well with:
|
||||
|
||||
- TypeScript's built-in type checking
|
||||
- IDE integrations like VS Code's IntelliSense
|
||||
- Documentation generators that support TypeScript
|
||||
|
||||
## TypeScript-Specific Documentation Tags
|
||||
|
||||
````tsx
|
||||
/**
|
||||
* This function demonstrates TypeScript-native documentation
|
||||
*
|
||||
* @remarks
|
||||
* The remarks section provides additional details that wouldn't fit in the brief description.
|
||||
*
|
||||
* @typeParam T - Generic type parameter for the input array
|
||||
* @typeParam U - Generic type parameter for the output array
|
||||
*
|
||||
* @param items - Array of items to process (TypeScript infers the type)
|
||||
* @param mapper - Function to transform items (TypeScript infers the signature)
|
||||
* @returns Array of transformed items
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* // Transform numbers to strings
|
||||
* const numbers = [1, 2, 3];
|
||||
* const strings = mapItems(numbers, n => n.toString());
|
||||
* ```
|
||||
*/
|
||||
function mapItems<T, U>(items: T[], mapper: (item: T) => U): U[] {
|
||||
return items.map(mapper);
|
||||
}
|
||||
|
||||
/**
|
||||
* Interface for configuration options
|
||||
*
|
||||
* @public
|
||||
*/
|
||||
export interface ConfigOptions {
|
||||
/**
|
||||
* Base URL for API requests
|
||||
*/
|
||||
apiUrl: string;
|
||||
|
||||
/**
|
||||
* Authentication token
|
||||
* @defaultValue undefined
|
||||
*/
|
||||
token?: string;
|
||||
|
||||
/**
|
||||
* Request timeout in milliseconds
|
||||
* @defaultValue 3000
|
||||
*/
|
||||
timeout: number;
|
||||
}
|
||||
````
|
||||
|
||||
## Component JSDoc Template
|
||||
|
||||
````tsx
|
||||
/**
|
||||
* @component ComponentName
|
||||
* @description Brief description of what the component does
|
||||
*
|
||||
* @see [Optional] Link to design reference (e.g., Figma)
|
||||
*
|
||||
* [Optional: Additional context about the component's role in the application]
|
||||
*
|
||||
* @example
|
||||
* ```tsx
|
||||
* <ComponentName prop1="value" prop2={value} />
|
||||
* ```
|
||||
*
|
||||
* @dependencies
|
||||
* - DependencyComponent1
|
||||
* - DependencyComponent2
|
||||
*/
|
||||
````
|
||||
|
||||
## Props Interface Template
|
||||
|
||||
```tsx
|
||||
/**
|
||||
* Props for the ComponentName component
|
||||
* @interface ComponentNameProps
|
||||
* @property {Type} propName - Description of the prop
|
||||
* @property {Type} [optionalProp] - Description of the optional prop
|
||||
* @property {() => void} [onEvent] - Callback fired when event occurs
|
||||
*/
|
||||
interface ComponentNameProps {
|
||||
propName: Type;
|
||||
optionalProp?: Type;
|
||||
onEvent?: () => void;
|
||||
}
|
||||
```
|
||||
|
||||
## Function Template
|
||||
|
||||
```tsx
|
||||
/**
|
||||
* Description of what the function does
|
||||
* @function functionName
|
||||
* @param {ParamType} paramName - Description of the parameter
|
||||
* @returns {ReturnType} Description of the return value
|
||||
* @throws {ErrorType} Description of potential errors
|
||||
*/
|
||||
function functionName(paramName: ParamType): ReturnType {
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
## Type/Interface Template
|
||||
|
||||
```tsx
|
||||
/**
|
||||
* Description of what this type/interface represents
|
||||
* @interface InterfaceName
|
||||
* @property {Type} propertyName - Description of the property
|
||||
* @property {Type} [optionalProperty] - Description of the optional property
|
||||
*/
|
||||
interface InterfaceName {
|
||||
propertyName: Type;
|
||||
optionalProperty?: Type;
|
||||
}
|
||||
|
||||
/**
|
||||
* Description of this type alias
|
||||
* @type TypeName
|
||||
*/
|
||||
export type TypeName = BaseType & {
|
||||
additionalProperty: string;
|
||||
};
|
||||
|
||||
/**
|
||||
* Type for use with generic components
|
||||
* @template T - Description of the generic parameter
|
||||
*/
|
||||
export type GenericType<T> = {
|
||||
value: T;
|
||||
label: string;
|
||||
};
|
||||
```
|
||||
|
||||
## Enum Template
|
||||
|
||||
```tsx
|
||||
/**
|
||||
* Description of what this enum represents
|
||||
* @enum {string|number} EnumName
|
||||
*/
|
||||
export enum EnumName {
|
||||
/**
|
||||
* Description of this enum value
|
||||
*/
|
||||
VALUE_ONE = 'value_one',
|
||||
|
||||
/**
|
||||
* Description of this enum value
|
||||
*/
|
||||
VALUE_TWO = 'value_two',
|
||||
}
|
||||
```
|
||||
|
||||
## Const Assertion Template
|
||||
|
||||
```tsx
|
||||
/**
|
||||
* Description of this constant object
|
||||
* @const objectName
|
||||
*/
|
||||
export const objectName = {
|
||||
PROPERTY_ONE: 'value_one',
|
||||
PROPERTY_TWO: 'value_two',
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Type derived from const assertion
|
||||
* @type TypeFromConst
|
||||
*/
|
||||
export type TypeFromConst = (typeof objectName)[keyof typeof objectName];
|
||||
```
|
||||
|
||||
## Import/Export Type Guidelines
|
||||
|
||||
When working with TypeScript, use explicit type imports/exports for better clarity:
|
||||
|
||||
```tsx
|
||||
// Preferred: Explicit type imports
|
||||
import type { SomeType, AnotherInterface } from './types';
|
||||
import { Component } from './components';
|
||||
|
||||
// Preferred: Explicit type exports
|
||||
export type { ComponentProps } from './Component';
|
||||
export { Component } from './Component';
|
||||
|
||||
// For re-exporting both the type and value:
|
||||
export { default as Component, type ComponentProps } from './Component';
|
||||
```
|
||||
|
||||
## Barrel File (index.ts) Template
|
||||
|
||||
````tsx
|
||||
/**
|
||||
* @module ModuleName
|
||||
* @description Brief description of the module's purpose
|
||||
*
|
||||
* This barrel file exports all public components, hooks, and types from the module.
|
||||
* When importing from this module, use the following pattern:
|
||||
* ```tsx
|
||||
* import { ComponentA, ComponentB, useFeature } from '@/path/to/module';
|
||||
* ```
|
||||
*/
|
||||
|
||||
// Component exports
|
||||
export { ComponentA } from './ComponentA';
|
||||
export { ComponentB } from './ComponentB';
|
||||
|
||||
// Hook exports
|
||||
export { useFeatureA } from './hooks/useFeatureA';
|
||||
export { useFeatureB } from './hooks/useFeatureB';
|
||||
|
||||
// Type exports - use explicit type exports
|
||||
export type { ComponentAProps } from './ComponentA';
|
||||
export type { ComponentBProps } from './ComponentB';
|
||||
|
||||
// Enum exports
|
||||
export { FeatureEnum } from './types';
|
||||
|
||||
// Re-export all from a sub-module (use sparingly)
|
||||
export * from './submodule';
|
||||
````
|
||||
|
||||
## Component with Subcomponents Template
|
||||
|
||||
````tsx
|
||||
/**
|
||||
* Parent component description
|
||||
* @component ParentComponent
|
||||
* @description Overview of the parent component
|
||||
*
|
||||
* @see [Optional] Link to design reference
|
||||
*
|
||||
* Component Hierarchy:
|
||||
* - ParentComponent
|
||||
* - SubComponent1
|
||||
* - SubComponent2
|
||||
* - NestedComponent
|
||||
*
|
||||
* @example
|
||||
* ```tsx
|
||||
* <ParentComponent prop1="value" prop2={value} />
|
||||
* ```
|
||||
*/
|
||||
export function ParentComponent({ prop1, prop2 }: ParentComponentProps) {
|
||||
// Implementation
|
||||
}
|
||||
|
||||
/**
|
||||
* Subcomponent description
|
||||
* @component SubComponent
|
||||
* @description Overview of the subcomponent
|
||||
* @private Only used within ParentComponent
|
||||
*/
|
||||
function SubComponent({ subProp }: SubComponentProps) {
|
||||
// Implementation
|
||||
}
|
||||
````
|
||||
|
||||
## Hooks Template
|
||||
|
||||
````tsx
|
||||
/**
|
||||
* Description of what the hook does and when to use it
|
||||
* @hook useHookName
|
||||
*
|
||||
* @example
|
||||
* ```tsx
|
||||
* const { value, setValue } = useHookName(initialValue)
|
||||
* ```
|
||||
*
|
||||
* @param {ParamType} initialValue - Description of the parameter
|
||||
* @returns {ReturnType} Description of the return value
|
||||
*/
|
||||
function useHookName(initialValue: ParamType): ReturnType {
|
||||
// Implementation
|
||||
}
|
||||
````
|
||||
|
||||
## Store Documentation Template
|
||||
|
||||
````tsx
|
||||
/**
|
||||
* Description of what the store manages
|
||||
* @store storeName
|
||||
*
|
||||
* @example
|
||||
* ```tsx
|
||||
* const { value, setValue } = useStore()
|
||||
* ```
|
||||
*
|
||||
* State Management:
|
||||
* - value: Description of state value
|
||||
* - setValue: Description of state updater
|
||||
*/
|
||||
````
|
||||
|
||||
## Additional Guidelines
|
||||
|
||||
1. **Be concise but complete** - Provide enough information to understand the component without
|
||||
overwhelming the reader
|
||||
2. **Document public API** - Focus on documenting the public API rather than implementation details
|
||||
3. **Keep examples simple** - Examples should demonstrate common use cases
|
||||
4. **Update documentation** - Keep documentation in sync with code changes
|
||||
5. **Document side effects** - Clearly document any side effects or behaviors that might not be
|
||||
obvious
|
||||
|
||||
## When to Document
|
||||
|
||||
- All components, hooks, and utilities exported from a package or module
|
||||
- Complex internal functions that are difficult to understand at a glance
|
||||
- Props, especially those with non-obvious behavior
|
||||
- State management code and side effects
|
||||
|
||||
## TypeScript-Specific JSDoc Tags
|
||||
|
||||
TypeScript supports JSDoc with additional TypeScript-specific tags. Use these tags to enhance your
|
||||
documentation:
|
||||
|
||||
```tsx
|
||||
/**
|
||||
* @typeParam T - Type parameter description (preferred over @template)
|
||||
* @param param - Parameter with TypeScript type inference (no need for {type})
|
||||
* @returns Return value with TypeScript type inference
|
||||
* @defaultValue Default value for a property
|
||||
* @public Indicates this is part of the public API
|
||||
* @private Indicates this is a private member
|
||||
* @protected Indicates this is a protected member
|
||||
* @readonly Indicates this is a readonly property
|
||||
* @deprecated Indicates this is deprecated with optional explanation
|
||||
*/
|
||||
|
||||
// Property documentation in interfaces/classes
|
||||
interface Example {
|
||||
/**
|
||||
* Property description
|
||||
* @defaultValue 'default'
|
||||
*/
|
||||
property: string;
|
||||
}
|
||||
|
||||
// Documentation for React component props using type alias
|
||||
type ButtonProps = {
|
||||
/**
|
||||
* The button's variant style
|
||||
* @defaultValue 'primary'
|
||||
*/
|
||||
variant?: 'primary' | 'secondary' | 'tertiary';
|
||||
|
||||
/**
|
||||
* Content to display inside the button
|
||||
*/
|
||||
children: React.ReactNode;
|
||||
|
||||
/**
|
||||
* Called when the button is clicked
|
||||
*/
|
||||
onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
|
||||
};
|
||||
|
||||
/**
|
||||
* Function documentation using modern TypeScript patterns
|
||||
*
|
||||
* @deprecated Use newFunction instead
|
||||
* @throws Error when input is invalid
|
||||
*/
|
||||
function oldFunction(input: string): void {
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
## Mermaid Diagrams
|
||||
|
||||
Use Mermaid diagrams to visualize complex relationships, flows, or processes. Include Mermaid
|
||||
diagrams directly in markdown documentation using the following formats:
|
||||
|
||||
### Component Relationship Diagram
|
||||
|
||||
````markdown
|
||||
/\*\*
|
||||
|
||||
- @component ComplexFeature
|
||||
- @description A complex feature with multiple components
|
||||
-
|
||||
- ## Component Relationships
|
||||
- ```mermaid
|
||||
|
||||
```
|
||||
|
||||
- graph TD
|
||||
- A[ParentComponent] --> B[ChildComponent1]
|
||||
- A --> C[ChildComponent2]
|
||||
- B --> D[GrandchildComponent1]
|
||||
- B --> E[GrandchildComponent2]
|
||||
- C --> F[GrandchildComponent3]
|
||||
- ```
|
||||
*/
|
||||
```
|
||||
````
|
||||
|
||||
### Data Flow Diagram
|
||||
|
||||
````markdown
|
||||
/\*\*
|
||||
|
||||
- @module DataFlow
|
||||
- @description Shows how data flows through the application
|
||||
-
|
||||
- ## Data Flow
|
||||
- ```mermaid
|
||||
|
||||
```
|
||||
|
||||
- graph LR
|
||||
- API[API] --> Store[Store]
|
||||
- Store --> ComponentA[Component A]
|
||||
- Store --> ComponentB[Component B]
|
||||
- ComponentA --> User[User Interface]
|
||||
- ComponentB --> User
|
||||
- ```
|
||||
*/
|
||||
```
|
||||
````
|
||||
|
||||
### State Machine Diagram
|
||||
|
||||
````markdown
|
||||
/\*\*
|
||||
|
||||
- @component StatefulComponent
|
||||
- @description Component with complex state transitions
|
||||
-
|
||||
- ## State Machine
|
||||
- ```mermaid
|
||||
|
||||
```
|
||||
|
||||
- stateDiagram-v2
|
||||
- [*] --> Idle
|
||||
- Idle --> Loading: fetch()
|
||||
- Loading --> Success: data received
|
||||
- Loading --> Error: error thrown
|
||||
- Error --> Loading: retry()
|
||||
- Success --> Idle: reset()
|
||||
- Error --> Idle: reset()
|
||||
- ```
|
||||
*/
|
||||
```
|
||||
````
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
````markdown
|
||||
/\*\*
|
||||
|
||||
- @function authenticateUser
|
||||
- @description Authentication process flow
|
||||
-
|
||||
- ## Authentication Sequence
|
||||
- ```mermaid
|
||||
|
||||
```
|
||||
|
||||
- sequenceDiagram
|
||||
- participant User
|
||||
- participant Client
|
||||
- participant API
|
||||
- participant Database
|
||||
-
|
||||
- User->>Client: Enter credentials
|
||||
- Client->>API: POST /auth/login
|
||||
- API->>Database: Validate credentials
|
||||
- Database-->>API: Valid user
|
||||
- API-->>Client: JWT token
|
||||
- Client-->>User: Login success
|
||||
- ```
|
||||
*/
|
||||
```
|
||||
````
|
||||
|
||||
### When to Use Mermaid Diagrams
|
||||
|
||||
- Component hierarchy diagrams for complex nested components
|
||||
- Data flow diagrams for state management patterns
|
||||
- Process flows for complex business logic
|
||||
- State machines for components with multiple states
|
||||
- Sequence diagrams for asynchronous operations
|
||||
|
||||
### Mermaid Diagram Guidelines
|
||||
|
||||
1. Keep diagrams simple and focused on one aspect of the system
|
||||
2. Use consistent naming conventions in diagrams
|
||||
3. Add concise labels to explain relationships
|
||||
4. Include a brief text description above each diagram
|
||||
5. For complex diagrams, consider breaking them into multiple smaller diagrams
|
||||
@@ -0,0 +1,232 @@
|
||||
# Feature Building Process
|
||||
|
||||
This document outlines our standardized approach to building new features. Following this process
|
||||
ensures that features are well-designed, properly structured, thoroughly documented, and
|
||||
consistently implemented.
|
||||
|
||||
## 1. Design and Data Flow Analysis
|
||||
|
||||
Before writing any code, thoroughly analyze the design and data flow requirements:
|
||||
|
||||
### Design Analysis
|
||||
|
||||
- Study the Figma/design mockups thoroughly
|
||||
- Identify all UI components and their states
|
||||
- Note interactions, animations, and transitions
|
||||
- Identify responsive behavior requirements
|
||||
- Document accessibility considerations
|
||||
|
||||
### Data Flow Analysis
|
||||
|
||||
- Map out the data requirements for the feature
|
||||
- Identify data sources and sinks
|
||||
- Document API endpoints that will be used
|
||||
- Define state management needs
|
||||
- Identify where data transformations occur
|
||||
- Document any caching or persistence requirements
|
||||
|
||||
### Output
|
||||
|
||||
Create a Design & Data Requirements document containing:
|
||||
|
||||
- Screenshots/references to relevant design mockups
|
||||
- Component breakdown with states and props
|
||||
- Data flow diagram
|
||||
- API contract expectations
|
||||
- State management approach
|
||||
|
||||
## 2. Structure Planning
|
||||
|
||||
Once the design and data requirements are understood, plan the structure:
|
||||
|
||||
### Routing
|
||||
|
||||
- Define all routes needed for the feature
|
||||
- Document route parameters and query parameters
|
||||
- Specify layout components for each route
|
||||
- Define route guards or access control
|
||||
|
||||
### Component Hierarchy
|
||||
|
||||
- Create a component tree showing parent-child relationships
|
||||
- Identify reusable components vs. feature-specific components
|
||||
- Define prop interfaces for all components
|
||||
- Document component responsibilities and boundaries
|
||||
|
||||
### File Structure
|
||||
|
||||
- Plan the directory structure following project conventions
|
||||
- Define file naming following established patterns
|
||||
- Identify shared utilities, hooks, or helpers needed
|
||||
- Plan test file organization
|
||||
|
||||
### Output
|
||||
|
||||
Create a Structure Plan document containing:
|
||||
|
||||
- Route definitions
|
||||
- Component hierarchy diagram
|
||||
- Directory and file structure plan
|
||||
- List of new files to create with their purpose
|
||||
|
||||
## 3. File Creation with Documentation
|
||||
|
||||
Create skeleton files with comprehensive documentation:
|
||||
|
||||
### For Each Component:
|
||||
|
||||
- Purpose and responsibility
|
||||
- Props interface with detailed documentation
|
||||
- State management approach
|
||||
- Side effects and cleanup
|
||||
- Error handling approach
|
||||
- Expected behaviors for all edge cases
|
||||
- Performance considerations
|
||||
- Testing strategy
|
||||
|
||||
### For Data/API Files:
|
||||
|
||||
- Type definitions
|
||||
- Function signatures with parameters and return types
|
||||
- Error handling approach
|
||||
- Caching strategy
|
||||
- Retry logic
|
||||
|
||||
### For Hooks/Utilities:
|
||||
|
||||
- Purpose and usage examples
|
||||
- Parameters and return values
|
||||
- Side effects
|
||||
- Error scenarios
|
||||
- Performance characteristics
|
||||
|
||||
### Output
|
||||
|
||||
A set of skeleton files with detailed JSDoc comments outlining implementation requirements for each
|
||||
file.
|
||||
|
||||
## 4. Implementation Guide
|
||||
|
||||
Create a comprehensive guide for engineers or AI agents to follow:
|
||||
|
||||
### Implementation Order
|
||||
|
||||
- Dependency graph showing which files should be implemented first
|
||||
- Recommended implementation sequence
|
||||
|
||||
### Critical Requirements
|
||||
|
||||
- Performance requirements
|
||||
- Accessibility requirements
|
||||
- Browser/device compatibility requirements
|
||||
- Error handling expectations
|
||||
|
||||
### Testing Requirements
|
||||
|
||||
- Unit test coverage expectations
|
||||
- Integration test scenarios
|
||||
- E2E test scenarios
|
||||
|
||||
### What NOT to Do
|
||||
|
||||
- Anti-patterns to avoid
|
||||
- Performance pitfalls
|
||||
- Security concerns
|
||||
- Common mistakes
|
||||
|
||||
### Review Checklist
|
||||
|
||||
- Code quality checks
|
||||
- Performance review points
|
||||
- Accessibility review points
|
||||
- Security review points
|
||||
|
||||
## Example: Feature Building for a User Profile Page
|
||||
|
||||
### 1. Design & Data Analysis
|
||||
|
||||
```
|
||||
Design Requirements:
|
||||
- Profile page with user avatar, name, email, and bio
|
||||
- Edit profile form with validation
|
||||
- Activity feed showing recent actions
|
||||
...
|
||||
|
||||
Data Requirements:
|
||||
- User profile data from GET /api/users/:id
|
||||
- Profile updates via PUT /api/users/:id
|
||||
- Activity data from GET /api/users/:id/activity
|
||||
...
|
||||
```
|
||||
|
||||
### 2. Structure Plan
|
||||
|
||||
```
|
||||
Routes:
|
||||
- /profile - Main profile view
|
||||
- /profile/edit - Edit profile form
|
||||
|
||||
Components:
|
||||
- ProfilePage
|
||||
- ProfileHeader
|
||||
- ActivityFeed
|
||||
- ActivityItem
|
||||
- ProfileEditForm
|
||||
- ImageUploader
|
||||
- FormFields
|
||||
...
|
||||
```
|
||||
|
||||
### 3. File Skeleton (Example for ProfileHeader.tsx)
|
||||
|
||||
```tsx
|
||||
/**
|
||||
* @component ProfileHeader
|
||||
* @description Displays the user's profile header with avatar, name, and key information
|
||||
*
|
||||
* Requirements:
|
||||
* - Display user avatar with fallback for missing images
|
||||
* - Show user name, handle, and join date
|
||||
* - Display edit button only if user is viewing their own profile
|
||||
* - Show verified badge if account is verified
|
||||
* - Handle loading and error states
|
||||
* ...
|
||||
*/
|
||||
```
|
||||
|
||||
### 4. Implementation Guide (Excerpt)
|
||||
|
||||
```
|
||||
Implementation Order:
|
||||
1. Types and API functions
|
||||
2. Hooks for data fetching
|
||||
3. Base components (ProfileHeader, ActivityItem)
|
||||
4. Container components (ProfilePage, ActivityFeed)
|
||||
5. Form components
|
||||
|
||||
Do NOT:
|
||||
- Make direct API calls from components - use the defined hooks
|
||||
- Store sensitive user data in localStorage
|
||||
- Use inline styles except for dynamically calculated values
|
||||
- Implement custom form validation - use the specified validation library
|
||||
...
|
||||
```
|
||||
|
||||
## Process Checklist
|
||||
|
||||
- [ ] Complete Design & Data Flow Analysis
|
||||
- [ ] Create Structure Plan
|
||||
- [ ] Create Skeleton Files with Documentation
|
||||
- [ ] Develop Implementation Guide
|
||||
- [ ] Review and Finalize Feature Building Documents
|
||||
- [ ] Implement Feature Following Guide
|
||||
- [ ] Review Implementation Against Requirements
|
||||
|
||||
By following this standardized feature building process, we ensure that features are implemented
|
||||
consistently, with clear documentation, and according to best practices.
|
||||
|
||||
## Getting Started
|
||||
|
||||
To start building a new feature using this process, use the
|
||||
[Feature Building Template](./FEATURE_BUILDING_TEMPLATE.md) as a starting point. This template
|
||||
provides a structured document that you can fill in with the specific details for your feature.
|
||||
@@ -0,0 +1,239 @@
|
||||
# Feature Building: [Feature Name]
|
||||
|
||||
> This is a template for the Feature Building process. Replace placeholder text with actual content
|
||||
> for your feature.
|
||||
|
||||
## 1. Design and Data Flow Analysis
|
||||
|
||||
### Design Analysis
|
||||
|
||||
#### UI Components
|
||||
|
||||
- Component 1: [Description, states, interactions]
|
||||
- Component 2: [Description, states, interactions]
|
||||
- ...
|
||||
|
||||
#### Interactions and Animations
|
||||
|
||||
- Interaction 1: [Description]
|
||||
- Animation 1: [Description]
|
||||
- ...
|
||||
|
||||
#### Responsive Behavior
|
||||
|
||||
- Mobile: [Description]
|
||||
- Tablet: [Description]
|
||||
- Desktop: [Description]
|
||||
|
||||
#### Accessibility Considerations
|
||||
|
||||
- [List accessibility requirements]
|
||||
|
||||
### Data Flow Analysis
|
||||
|
||||
#### Data Requirements
|
||||
|
||||
- Data Entity 1: [Properties, validation rules]
|
||||
- Data Entity 2: [Properties, validation rules]
|
||||
- ...
|
||||
|
||||
#### API Endpoints
|
||||
|
||||
- Endpoint 1: `[METHOD] /path` - [Purpose, request/response format]
|
||||
- Endpoint 2: `[METHOD] /path` - [Purpose, request/response format]
|
||||
- ...
|
||||
|
||||
#### State Management
|
||||
|
||||
- Global State: [What needs to be in global state]
|
||||
- Local State: [What can be kept in component state]
|
||||
- Derived State: [What can be computed from other state]
|
||||
|
||||
#### Data Transformations
|
||||
|
||||
- [Describe any transformations needed between API and UI]
|
||||
|
||||
#### Caching/Persistence
|
||||
|
||||
- [Describe caching or persistence requirements]
|
||||
|
||||
## 2. Structure Planning
|
||||
|
||||
### Routing
|
||||
|
||||
#### Routes
|
||||
|
||||
- `/route1`: [Purpose, parameters]
|
||||
- `/route2`: [Purpose, parameters]
|
||||
- ...
|
||||
|
||||
#### Layouts
|
||||
|
||||
- Route 1 Layout: [Description]
|
||||
- Route 2 Layout: [Description]
|
||||
- ...
|
||||
|
||||
#### Access Control
|
||||
|
||||
- [Describe any route guards or access control]
|
||||
|
||||
### Component Hierarchy
|
||||
|
||||
```
|
||||
ParentComponent
|
||||
├── ChildComponent1
|
||||
│ ├── GrandchildComponent1
|
||||
│ └── GrandchildComponent2
|
||||
└── ChildComponent2
|
||||
```
|
||||
|
||||
#### Component Interfaces
|
||||
|
||||
- Component 1 Props: [Props description]
|
||||
- Component 2 Props: [Props description]
|
||||
- ...
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
feature-name/
|
||||
├── index.ts
|
||||
├── types.ts
|
||||
├── components/
|
||||
│ ├── ComponentOne.tsx
|
||||
│ └── ComponentTwo.tsx
|
||||
├── hooks/
|
||||
│ └── useFeatureData.ts
|
||||
└── utils/
|
||||
└── featureUtils.ts
|
||||
```
|
||||
|
||||
#### New Files to Create
|
||||
|
||||
- `feature-name/index.ts`: [Purpose]
|
||||
- `feature-name/types.ts`: [Purpose]
|
||||
- ...
|
||||
|
||||
## 3. File Skeletons
|
||||
|
||||
### `feature-name/index.ts`
|
||||
|
||||
````typescript
|
||||
/**
|
||||
* @module FeatureName
|
||||
* @description [Brief description of the feature]
|
||||
*
|
||||
* This module exports the main components and hooks for the [Feature Name] feature.
|
||||
*
|
||||
* @example
|
||||
* ```tsx
|
||||
* import { FeatureComponent } from '@/features/feature-name';
|
||||
*
|
||||
* function MyComponent() {
|
||||
* return <FeatureComponent />;
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
|
||||
export * from './components/ComponentOne';
|
||||
// Add additional exports
|
||||
````
|
||||
|
||||
### `feature-name/components/ComponentOne.tsx`
|
||||
|
||||
````typescript
|
||||
/**
|
||||
* @component ComponentOne
|
||||
* @description [Description of the component]
|
||||
*
|
||||
* Requirements:
|
||||
* - [Requirement 1]
|
||||
* - [Requirement 2]
|
||||
* - ...
|
||||
*
|
||||
* States:
|
||||
* - Loading: [Description]
|
||||
* - Error: [Description]
|
||||
* - Success: [Description]
|
||||
*
|
||||
* @example
|
||||
* ```tsx
|
||||
* <ComponentOne prop1="value" />
|
||||
* ```
|
||||
*/
|
||||
|
||||
// Implementation details will go here
|
||||
````
|
||||
|
||||
### [Add skeleton documentation for all planned files]
|
||||
|
||||
## 4. Implementation Guide
|
||||
|
||||
### Implementation Order
|
||||
|
||||
1. Create `types.ts` with all required interfaces
|
||||
2. Implement API utilities and hooks
|
||||
3. Implement base UI components
|
||||
4. Implement container components
|
||||
5. Connect components to data sources
|
||||
6. Implement routing and navigation
|
||||
|
||||
### Critical Requirements
|
||||
|
||||
#### Performance
|
||||
|
||||
- [List performance requirements]
|
||||
|
||||
#### Accessibility
|
||||
|
||||
- [List accessibility requirements]
|
||||
|
||||
#### Compatibility
|
||||
|
||||
- [List browser/device compatibility requirements]
|
||||
|
||||
#### Error Handling
|
||||
|
||||
- [List error handling expectations]
|
||||
|
||||
### Testing Requirements
|
||||
|
||||
#### Unit Tests
|
||||
|
||||
- Component 1: [Test scenarios]
|
||||
- Component 2: [Test scenarios]
|
||||
- ...
|
||||
|
||||
#### Integration Tests
|
||||
|
||||
- [List integration test scenarios]
|
||||
|
||||
#### E2E Tests
|
||||
|
||||
- [List E2E test scenarios]
|
||||
|
||||
### What NOT to Do
|
||||
|
||||
- ❌ [Anti-pattern 1]
|
||||
- ❌ [Anti-pattern 2]
|
||||
- ...
|
||||
|
||||
### Review Checklist
|
||||
|
||||
- [ ] Code follows project style guide
|
||||
- [ ] Components are properly documented
|
||||
- [ ] All critical requirements are met
|
||||
- [ ] Tests cover main functionality
|
||||
- [ ] Accessibility guidelines are followed
|
||||
- [ ] Performance is satisfactory
|
||||
- [ ] Error handling is comprehensive
|
||||
|
||||
## Process Checklist
|
||||
|
||||
- [ ] Complete Design & Data Flow Analysis
|
||||
- [ ] Create Structure Plan
|
||||
- [ ] Create Skeleton Files with Documentation
|
||||
- [ ] Develop Implementation Guide
|
||||
- [ ] Review and Finalize Feature Building Documents
|
||||
- [ ] Implement Feature Following Guide
|
||||
- [ ] Review Implementation Against Requirements
|
||||
@@ -0,0 +1,89 @@
|
||||
# Snowball Tools Project Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
This document consolidates project standards, documentation guidelines, and best practices for the
|
||||
Snowball Tools project.
|
||||
|
||||
## Project Purpose and Standards
|
||||
|
||||
### Core Principles
|
||||
|
||||
1. **Consistency** - Establish consistent patterns across the codebase
|
||||
2. **Onboarding** - Help new developers understand project conventions
|
||||
3. **Maintainability** - Make code easier to maintain and extend
|
||||
4. **Quality** - Encourage best practices that lead to higher quality code
|
||||
|
||||
## Documentation Standards
|
||||
|
||||
### TSDoc and TypeDoc
|
||||
|
||||
We use [TSDoc](https://tsdoc.org/) for documenting TypeScript code and
|
||||
[TypeDoc](https://typedoc.org/) for generating API documentation.
|
||||
|
||||
#### Basic Comment Structure
|
||||
|
||||
TSDoc comments start with `/**` and end with `*/`:
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* This is a TSDoc comment.
|
||||
*/
|
||||
```
|
||||
|
||||
#### Common TSDoc Tags
|
||||
|
||||
| Tag | Description |
|
||||
| ----------------------------------- | ----------------------------------------- |
|
||||
| `@param` | Documents a function parameter |
|
||||
| `@returns` | Documents the return value |
|
||||
| `@throws` | Documents exceptions that might be thrown |
|
||||
| `@example` | Provides an example of usage |
|
||||
| `@remarks` | Adds additional information |
|
||||
| `@deprecated` | Marks an item as deprecated |
|
||||
| `@see` | Refers to related documentation |
|
||||
| `@public`, `@protected`, `@private` | Visibility modifiers |
|
||||
|
||||
### Documentation Best Practices
|
||||
|
||||
1. **Document Public APIs**: Always document public APIs thoroughly
|
||||
2. **Include Examples**: Provide examples for complex functions or classes
|
||||
3. **Be Concise**: Keep documentation clear and to the point
|
||||
4. **Use Proper Grammar**: Use proper grammar and punctuation
|
||||
5. **Update Documentation**: Keep documentation in sync with code changes
|
||||
6. **Document Parameters**: Document all parameters, including their types and purpose
|
||||
7. **Document Return Values**: Document what a function returns
|
||||
8. **Document Exceptions**: Document any exceptions that might be thrown
|
||||
|
||||
## Generating Documentation
|
||||
|
||||
Generate documentation:
|
||||
|
||||
```bash
|
||||
yarn docs
|
||||
```
|
||||
|
||||
Watch and regenerate documentation:
|
||||
|
||||
```bash
|
||||
yarn docs:watch
|
||||
```
|
||||
|
||||
## Contributing to Standards
|
||||
|
||||
To suggest changes or additions to project standards:
|
||||
|
||||
1. Discuss proposed changes with the team
|
||||
2. Update the relevant documentation
|
||||
3. Provide examples demonstrating the benefits of the proposed changes
|
||||
|
||||
## Enforcement
|
||||
|
||||
While these standards are not automatically enforced, developers are encouraged to follow them, and
|
||||
code reviewers should check for adherence to these guidelines.
|
||||
|
||||
## Resources
|
||||
|
||||
- [TSDoc Official Documentation](https://tsdoc.org/)
|
||||
- [TypeDoc Official Documentation](https://typedoc.org/)
|
||||
- [TypeScript Documentation](https://www.typescriptlang.org/docs/)
|
||||
@@ -0,0 +1,128 @@
|
||||
# React Component Organization Conventions
|
||||
|
||||
## Feature-Based Organization
|
||||
|
||||
Group related components into feature folders:
|
||||
|
||||
```
|
||||
src/
|
||||
features/
|
||||
navigation/ # Feature group
|
||||
README.md # Feature documentation with architecture diagrams
|
||||
page-header/ # Component
|
||||
page-wrapper/ # Component
|
||||
sidebar/ # Component
|
||||
auth/ # Another feature group
|
||||
dashboard/ # Another feature group
|
||||
```
|
||||
|
||||
## Component Folder Structure
|
||||
|
||||
For each component that requires co-located files (types, tests, etc.):
|
||||
|
||||
```
|
||||
component-name/
|
||||
- ComponentName.tsx # Main component implementation
|
||||
- types.ts # Component-specific types
|
||||
- ComponentName.test.tsx # Component tests
|
||||
- README.md # Component-specific documentation
|
||||
- index.ts # Barrel exports
|
||||
```
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
- **Folders**: Use kebab-case (`page-header/`)
|
||||
- **Component Files**: Use PascalCase matching export name (`PageHeader.tsx`)
|
||||
- **Type Files**: Use `types.ts` for component-specific types
|
||||
- **Test Files**: Use component name with `.test.tsx` suffix (`PageHeader.test.tsx`)
|
||||
- **Index Files**: Always use `index.ts` for barrel exports
|
||||
|
||||
## Styling Conventions
|
||||
|
||||
- **Use Tailwind**: Always use Tailwind classes for styling instead of CSS files or inline styles
|
||||
- **Use UI Components**: Leverage existing UI components from `components/ui` directory
|
||||
- **No External CSS**: Never import external CSS files
|
||||
- **No New Libraries**: Do not add new dependencies; use existing ones
|
||||
- **Follow Patterns**: Match styling patterns used in the existing codebase
|
||||
|
||||
## Export Patterns
|
||||
|
||||
**Component File (PageHeader.tsx)**:
|
||||
```typescript
|
||||
export interface PageHeaderProps {
|
||||
title: string;
|
||||
subtitle?: string;
|
||||
}
|
||||
|
||||
export const PageHeader = ({ title, subtitle }: PageHeaderProps) => {
|
||||
return (
|
||||
// Component implementation
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
**Types File (types.ts)**:
|
||||
```typescript
|
||||
export interface PageHeaderTheme {
|
||||
backgroundColor: string;
|
||||
textColor: string;
|
||||
}
|
||||
|
||||
// Additional component-specific types
|
||||
```
|
||||
|
||||
**Barrel File (index.ts)**:
|
||||
```typescript
|
||||
export * from './PageHeader';
|
||||
export * from './types';
|
||||
```
|
||||
|
||||
## Import Examples
|
||||
|
||||
```typescript
|
||||
// Import specific component
|
||||
import { PageHeader } from '../components/page-header/PageHeader';
|
||||
|
||||
// Import via barrel
|
||||
import { PageHeader, PageHeaderTheme } from '../components/page-header';
|
||||
```
|
||||
|
||||
## Feature Documentation
|
||||
|
||||
Each feature folder should include a comprehensive README.md:
|
||||
|
||||
```markdown
|
||||
# Navigation Components
|
||||
|
||||
## Overview
|
||||
This module contains all navigation-related components for the application.
|
||||
|
||||
## Architecture
|
||||
```mermaid
|
||||
graph TD
|
||||
App --> PageWrapper
|
||||
PageWrapper --> PageHeader
|
||||
PageWrapper --> Sidebar
|
||||
PageWrapper --> MainContent
|
||||
PageHeader --> Breadcrumbs
|
||||
PageHeader --> UserMenu
|
||||
```
|
||||
|
||||
## Components
|
||||
- **PageHeader**: Application header with navigation controls
|
||||
- **PageWrapper**: Layout wrapper for all pages
|
||||
- **Sidebar**: Main navigation sidebar
|
||||
```
|
||||
|
||||
## Benefits of this Approach
|
||||
|
||||
- Avoids "index.tsx maze" - component location is always clear
|
||||
- Easier debugging (stack traces point to actual component files)
|
||||
- Feature-based organization provides clear domain boundaries
|
||||
- Architecture documentation with visual diagrams improves onboarding
|
||||
- Maintains logical co-location while separating concerns
|
||||
- Enables precise imports when needed
|
||||
- Follows widely accepted React community standards
|
||||
- Scales well with large component libraries
|
||||
|
||||
This convention balances maintainability with developer experience and remains effective as your application grows.
|
||||
Reference in New Issue
Block a user