chore: update skill
This commit is contained in:
parent
79304d1009
commit
605feabb40
|
|
@ -19,7 +19,7 @@ How you work:
|
|||
|
||||
- Who uses it: the public, 1–20 million visitors a day (Amazon, eBay, Digikala).
|
||||
- App: Next.js App Router, routes in `apps/<app>/src/app/`.
|
||||
- Business logic: `platforms/<app>/`; the app stays thin.
|
||||
- Business logic: `platforms/<platform>/`, one per product and shared by its apps; each app stays thin.
|
||||
- Server entry: every project except apps has `src/server.ts`.
|
||||
- Critical: a fresh server render per request with no server cache, web vitals, bundle and chunk size, and hydration and navigation speed.
|
||||
|
||||
|
|
@ -84,7 +84,7 @@ Error handling, patterns, and refactoring have their own references. Read each o
|
|||
|
||||
**Dependency direction**
|
||||
|
||||
- apps → platforms → packages. Nothing imports upward, and one product's app or platform never imports another's. ESLint enforces this through Nx tags.
|
||||
- apps → platforms → packages. Nothing imports upward, apps never import each other, and one product's app or platform never imports another's. ESLint enforces this through Nx tags.
|
||||
- island follows atomic design: atoms → molecules → organisms → templates, and a level never imports a level above it. `primitives/` are non-visual structural pieces (for example a portal) outside that ladder. The `components/` and `hooks/` inside an organism are private to it, except a compound component's named parts, which its `index.ts` re-exports.
|
||||
|
||||
**Features are DDD** (`features/<feature>/`)
|
||||
|
|
@ -124,7 +124,7 @@ Error handling, patterns, and refactoring have their own references. Read each o
|
|||
**Design system (island)**
|
||||
|
||||
- Build UI from island. Never fork or restyle an island component inside a feature; add a variant to island and use it.
|
||||
- Place every new component in three steps: reuse or add a variant first, then pick its level by what it renders and imports (never by its size), then its owner by whether it knows a domain. A domain-free organism that one route uses stays in that route's `organisms/` until a second route needs it, then moves to island. Details: [references/project-structure.md](references/project-structure.md#choosing-where-a-component-goes).
|
||||
- Place every new component in three steps: reuse or add a variant first, then pick its level by what it renders and imports (never by its size), then its owner by whether it knows a domain. A domain-free organism that one route uses stays in that route's `organisms/` until a second route needs it, then moves to island. An organism or template that knows a domain and serves several routes, or the same route in several apps, goes to the platform's `screens/`, at the nearest route level they share. Details: [references/project-structure.md](references/project-structure.md#choosing-where-a-component-goes).
|
||||
- Components use semantic tokens (`--color-surface-card`, `--color-text-muted`, `--color-action-primary`) layered over primitive tokens in `theme.css`. That layering is what makes theming and dark mode possible without a rewrite.
|
||||
- Every component defines its variants, sizes, and states (default, hover, focus-visible, active, disabled, loading, error, selected) and its accessibility behavior. Enabled interactive elements show `cursor: pointer` and disabled ones `cursor: not-allowed`, built into the component so no page can forget them.
|
||||
- Complex organisms are compound components (`<DataTable>`, `<DataTable.Toolbar>`, `<DataTable.Pagination>`) that share state through context, with slots or render props for the parts that vary per entity, such as cells, empty states, and toolbars.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Code patterns
|
||||
|
||||
Reference implementations for each layer. Paths are relative to the project that owns the code: `platforms/<app>/src/` for an app's logic and `packages/<name>/src/` for shared packages. `@project` is the workspace scope. The `@project/libs/*` APIs shown follow the lib specs: `http` and `isHttpError` in [lib-http.md](lib-http.md), the error handler's functions in [lib-error-handler.md](lib-error-handler.md), `storage` in [lib-local-storage.md](lib-local-storage.md), `cookie` in [lib-cookie.md](lib-cookie.md). `eventEmitter` stands for the repo's own lib; match its real signature.
|
||||
Reference implementations for each layer. Paths are relative to the project that owns the code: `platforms/<platform>/src/` for a product's logic and `packages/<name>/src/` for shared packages. `@project` is the workspace scope. The `@project/libs/*` APIs shown follow the lib specs: `http` and `isHttpError` in [lib-http.md](lib-http.md), the error handler's functions in [lib-error-handler.md](lib-error-handler.md), `storage` in [lib-local-storage.md](lib-local-storage.md), `cookie` in [lib-cookie.md](lib-cookie.md). `eventEmitter` stands for the repo's own lib; match its real signature.
|
||||
|
||||
Caches, the page entrypoint, and server-to-client data live in [b2c-b2b.md](b2c-b2b.md).
|
||||
|
||||
|
|
@ -162,7 +162,7 @@ This is an excerpt. The real file defines every semantic token the components us
|
|||
```css
|
||||
@import 'tailwindcss' source('../');
|
||||
@import '@project/island/styles/island.css';
|
||||
@source '../../../../platforms/<app>/src';
|
||||
@source '../../../../platforms/<platform>/src';
|
||||
```
|
||||
|
||||
Tailwind generates only the classes it finds in registered sources. island registers itself in `island.css`; the app registers its own `src/`, its platform, and any integration that renders UI. CSS `@import` resolves package names through package.json `exports`, not TypeScript path aliases, so path-alias workspaces import `island.css` by relative path.
|
||||
|
|
|
|||
|
|
@ -70,7 +70,7 @@ Where a new implementation goes:
|
|||
| Exhaustive check | `assertNever` in `packages/tools/src/assert-never/` | `assertNever(value: never): never` throws. Call it in the `default` of every `switch` over a union |
|
||||
| Generic hook with no feature data, such as `useDebouncedValue` | `packages/tools/src/use-debounced-value/use-debounced-value.ts` when more than one project needs it; otherwise beside its only user, such as an organism's `hooks/` | A `use-<name>.ts` hook that takes plain values and imports only React. A hook that reads a store, a query, or a `*Payload` belongs in the owning feature's `models/` or beside its store |
|
||||
|
||||
The examples use feature paths relative to `platforms/<app>/src/`, as code-patterns.md does.
|
||||
The examples use feature paths relative to `platforms/<platform>/src/`, as code-patterns.md does.
|
||||
|
||||
**Strategy.** An order's status picks its badge in the order list, the order header, and the timeline. One map replaces the three switches, and `satisfies` makes a new status fail type-check until it has an entry.
|
||||
|
||||
|
|
@ -226,7 +226,7 @@ export const analytics: AnalyticsAdapter = {
|
|||
};
|
||||
```
|
||||
|
||||
`platforms/<app>/src/app/app-shell/AppShell.tsx`, reduced to the subscription.
|
||||
`platforms/<platform>/src/app/app-shell/AppShell.tsx`, reduced to the subscription.
|
||||
|
||||
```tsx
|
||||
'use client';
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
The code for [error-handling.md](error-handling.md): island's error boundary, `ErrorFallback`, the part, page, and app boundaries, `readOnServer`, and the query client's error settings. Read it only when you build or change one of these. A feature that uses them needs only error-handling.md.
|
||||
|
||||
Paths are relative to `platforms/<app>/src/`, as in [code-patterns.md](code-patterns.md). Each `error-boundaries/<name>/` module is shaped like `guards/`: the component or function, its `types.ts`, and `index.ts`.
|
||||
Paths are relative to `platforms/<platform>/src/`, as in [code-patterns.md](code-patterns.md). Each `error-boundaries/<name>/` module is shaped like `guards/`: the component or function, its `types.ts`, and `index.ts`.
|
||||
|
||||
**island's error boundary.** `packages/island/src/primitives/error-boundary/ErrorBoundary.tsx` is a class, because React has no hook for catching render errors. It knows nothing about HTTP or reporting; the fallback does that. Its `types.ts` declares `ErrorBoundaryProps`: `children`, `fallback: (props: { error: unknown; reset: () => void }) => ReactNode`, `onReset?`, and `resetKeys?: readonly unknown[]`.
|
||||
|
||||
|
|
|
|||
|
|
@ -254,7 +254,7 @@ setPlatformEnv({ catalogApiUrl: clientEnv.NEXT_PUBLIC_CATALOG_API_URL });
|
|||
http.configure({ baseUrl: clientEnv.NEXT_PUBLIC_API_URL });
|
||||
```
|
||||
|
||||
`platforms/<app>/src/features/catalog/http.ts` reads the platform's env. The server copy holds the internal address and the client copy the public one.
|
||||
`platforms/<platform>/src/features/catalog/http.ts` reads the platform's env. The server copy holds the internal address and the client copy the public one.
|
||||
|
||||
```ts
|
||||
import { http } from '@project/libs/http';
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
A full page for [b2c-b2b.md](b2c-b2b.md): device detection, caches, a server page loader, the page entrypoint, streamed parts, and query hydration. Read it when you add a new page, or a part that reads server data in a way the repo doesn't have yet. Otherwise copy the shape of an existing page.
|
||||
|
||||
`platforms/<app>/src/shared/utils/get-device.ts`
|
||||
`platforms/<platform>/src/shared/utils/get-device.ts`
|
||||
|
||||
```ts
|
||||
import 'server-only';
|
||||
|
|
@ -15,7 +15,7 @@ export async function getDevice(): Promise<'mobile' | 'desktop'> {
|
|||
}
|
||||
```
|
||||
|
||||
`platforms/<app>/src/features/catalog/caches/products.ts`
|
||||
`platforms/<platform>/src/features/catalog/caches/products.ts`
|
||||
|
||||
```ts
|
||||
import 'server-only';
|
||||
|
|
@ -32,7 +32,7 @@ export const getRelatedProducts = cache((id: string) =>
|
|||
export const getProductReviews = cache((id: string, page: number) => productsRepository.listReviews({ id, page }));
|
||||
```
|
||||
|
||||
`platforms/<app>/src/features/catalog/caches/server.ts`
|
||||
`platforms/<platform>/src/features/catalog/caches/server.ts`
|
||||
|
||||
```ts
|
||||
import 'server-only';
|
||||
|
|
@ -40,7 +40,7 @@ import 'server-only';
|
|||
export { getProduct, getProductReviews, getRelatedProducts } from './products';
|
||||
```
|
||||
|
||||
`platforms/<app>/src/server.ts`
|
||||
`platforms/<platform>/src/server.ts`
|
||||
|
||||
```ts
|
||||
import 'server-only';
|
||||
|
|
@ -125,7 +125,7 @@ export async function ProductReviews({ productId }: ProductReviewsProps) {
|
|||
}
|
||||
```
|
||||
|
||||
`platforms/<app>/src/features/catalog/models/product/use-product-reviews-part.ts`. Page 1 comes from the server; later pages load in the browser while the current page stays visible.
|
||||
`platforms/<platform>/src/features/catalog/models/product/use-product-reviews-part.ts`. Page 1 comes from the server; later pages load in the browser while the current page stays visible.
|
||||
|
||||
```ts
|
||||
import { keepPreviousData, useQuery } from '@tanstack/react-query';
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Project structure
|
||||
|
||||
`<placeholders>` are names you choose. `@project` stands for the workspace's npm scope.
|
||||
`<placeholders>` are names you choose. `@project` stands for the workspace's npm scope. A product has one platform and one or more apps that share it: `<app>` names an app, `<platform>` the product's platform, and `<product>` the product.
|
||||
|
||||
Contents: Top level · App · Platform · Feature anatomy · Shared · island · Choosing where a component goes · libs, integrations, and tools packages · Env flow · Nx tags and boundaries · Exports and tree-shaking
|
||||
|
||||
|
|
@ -8,7 +8,7 @@ Contents: Top level · App · Platform · Feature anatomy · Shared · island ·
|
|||
|
||||
```
|
||||
apps/ # deployable apps
|
||||
platforms/ # each app's logic, one project per app
|
||||
platforms/ # each product's logic, one project per product, shared by its apps
|
||||
packages/
|
||||
├── island/ # design system (atomic design)
|
||||
├── libs/ # framework-agnostic libraries, e.g. http and env
|
||||
|
|
@ -65,14 +65,14 @@ apps/<app>/src/
|
|||
```
|
||||
|
||||
- Pages are thin entrypoints. A page picks the mobile or the desktop template on the server, so no component branches on viewport size.
|
||||
- Every route level may keep its own `organisms/` and `templates/`, shaped like island organisms. They are not routable because they contain no `page.tsx`.
|
||||
- Every route level may keep its own `organisms/` and `templates/`, shaped like island organisms. They are not routable because they contain no `page.tsx`. They hold only what this route uses; UI that knows a domain and serves several routes or apps lives in the platform's `screens/`.
|
||||
- `styles/`, `configs/`, and `constants/` grow as needed; each keeps an `index.ts`.
|
||||
- The app holds no features, stores, or business logic; those live in `platforms/<app>/`.
|
||||
- The app holds no features, stores, or business logic; those live in `platforms/<platform>/`. Apps never import each other.
|
||||
|
||||
## Platform
|
||||
|
||||
```
|
||||
platforms/<app>/src/
|
||||
platforms/<platform>/src/
|
||||
├── app/
|
||||
│ ├── app-shell/ # top-level provider shell shared by the mobile and desktop views
|
||||
│ │ ├── AppShell.tsx
|
||||
|
|
@ -87,14 +87,24 @@ platforms/<app>/src/
|
|||
│ │ ├── error-fallback/ # ErrorFallback: what every boundary renders
|
||||
│ │ ├── status-empty-state/ # the not-found and no-access empty states
|
||||
│ │ └── read-on-server/ # readOnServer; server-only, exported through server.ts
|
||||
│ └── navigation/
|
||||
│ ├── navigation.ts # typed route paths and navigation menus
|
||||
│ ├── constants.ts
|
||||
│ ├── types.ts
|
||||
│ ├── hooks/
|
||||
│ │ └── use-<hook-name>.ts
|
||||
│ ├── components/ # navigation UI, shaped like organisms
|
||||
│ └── index.ts
|
||||
│ ├── navigation/
|
||||
│ │ ├── navigation.ts # typed route paths and navigation menus
|
||||
│ │ ├── constants.ts
|
||||
│ │ ├── types.ts
|
||||
│ │ ├── hooks/
|
||||
│ │ │ └── use-<hook-name>.ts
|
||||
│ │ ├── components/ # navigation UI, shaped like organisms
|
||||
│ │ └── index.ts
|
||||
│ └── screens/ # UI that knows a domain and serves several routes or apps
|
||||
│ ├── organisms/ # shared by routes with no common route level
|
||||
│ ├── templates/
|
||||
│ └── (auth)/ # mirrors the apps' route tree
|
||||
│ ├── organisms/ # shared by routes under (auth)
|
||||
│ ├── templates/
|
||||
│ └── auth/
|
||||
│ └── login/
|
||||
│ ├── organisms/ # shared by the login route of several apps, or by routes under it
|
||||
│ └── templates/
|
||||
├── features/ # DDD, see Feature anatomy
|
||||
├── stores/ # one store per feature or domain
|
||||
├── shared/ # see Shared
|
||||
|
|
@ -102,6 +112,14 @@ platforms/<app>/src/
|
|||
└── server.ts
|
||||
```
|
||||
|
||||
`screens/` holds organisms and templates that know a domain and that several routes, or the same route in several apps, use. They can't go to island, because island is domain-free. They can't go to an app's route level, because one route level can't serve another route or another app.
|
||||
|
||||
- Its folders mirror the route tree. A component sits at the nearest route level that every route using it shares. Create a level's folder only when something lives in it.
|
||||
- `organisms/` and `templates/` hold component modules shaped like island organisms.
|
||||
- Its components know a domain: they call a model or an action, read a store, or take a `*Payload`. The logic itself stays in the feature's models and actions, so the components stay presentational.
|
||||
- It is UI: it may import `features/`, `stores/`, `shared/`, the rest of `app/`, island, and integrations. Nothing in `features/`, `stores/`, or `shared/` imports it.
|
||||
- A module that reads caches is server-only, like `read-on-server/`: its entry is `server.ts`, and the platform's `server.ts` re-exports it.
|
||||
|
||||
## Feature anatomy
|
||||
|
||||
```
|
||||
|
|
@ -249,12 +267,12 @@ Then check the imports: nothing the component imports sits above its level. A co
|
|||
**3. Owner.** A component is domain-free when it takes only plain props (strings, numbers, its own prop types, `ReactNode` slots, and callbacks) and imports only island, libs, and tools. It knows a domain when it takes a `*Payload` type, calls a model or an action, reads a store, or shows a feature's text. First match wins.
|
||||
|
||||
1. Only one organism, template, or primitive uses it → that module's private `components/`, shaped like an atom.
|
||||
2. It's a route's mobile or desktop template → that route's `templates/`.
|
||||
2. It's a route's mobile or desktop template → that route's `templates/`. When several apps render the same template for that route → `screens/` at that route's path, such as `screens/(auth)/auth/login/templates/`.
|
||||
3. It knows a domain:
|
||||
- Navigation UI → `platforms/<app>/src/app/navigation/components/`.
|
||||
- Navigation UI → `platforms/<platform>/src/app/navigation/components/`.
|
||||
- Third-party UI, such as a chat widget or its facade → the integration's `components/`.
|
||||
- One route uses it → that route's `organisms/`.
|
||||
- Several routes use it → the `organisms/` of the nearest route level they share, such as `app/(shop)/organisms/`.
|
||||
- One route in one app uses it → that route's `organisms/` in the app.
|
||||
- Several routes, or the same route in several apps, use it → `platforms/<platform>/src/app/screens/`, in the `organisms/` or `templates/` of the nearest route level they share, such as `screens/(shop)/organisms/`. With no shared level, `screens/organisms/`.
|
||||
4. It's a domain-free organism that one route uses → that route's `organisms/`. When a second route needs it, move it to island's `organisms/` at once, as [refactoring.md](refactoring.md#when-and-how) describes; never copy it.
|
||||
5. Otherwise → island, in the folder of its level. Route levels hold only `organisms/` and `templates/`, so every domain-free atom and molecule goes to island at once.
|
||||
|
||||
|
|
@ -316,8 +334,8 @@ Default tags. Reuse the repo's own tags if it already has them.
|
|||
|
||||
| Project | Tags |
|
||||
|---|---|
|
||||
| `apps/<app>` | `type:app`, `scope:<app>` |
|
||||
| `platforms/<app>` | `type:platform`, `scope:<app>` |
|
||||
| `apps/<app>` | `type:app`, `scope:<product>` |
|
||||
| `platforms/<platform>` | `type:platform`, `scope:<product>` |
|
||||
| `packages/integrations` | `type:integration`, `scope:shared` |
|
||||
| `packages/island` | `type:ui`, `scope:shared` |
|
||||
| `packages/libs` | `type:lib`, `scope:shared` |
|
||||
|
|
@ -333,7 +351,7 @@ Default tags. Reuse the repo's own tags if it already has them.
|
|||
| `type:ui` | `type:lib`, `type:tool` |
|
||||
| `type:lib` | `type:tool` |
|
||||
| `type:tool` | Nothing |
|
||||
| `scope:<app>` | `scope:<app>`, `scope:shared` |
|
||||
| `scope:<product>` | `scope:<product>`, `scope:shared` |
|
||||
| `scope:shared` | `scope:shared` |
|
||||
|
||||
Layer rules inside a project are checked in review, or by `eslint-plugin-boundaries` when the repo configures it:
|
||||
|
|
@ -341,6 +359,7 @@ Layer rules inside a project are checked in review, or by `eslint-plugin-boundar
|
|||
- island: no import from a higher atomic level; an organism's `components/` and `hooks/` stay private.
|
||||
- features: the layer order in Feature anatomy.
|
||||
- `shared/`: imports nothing above it.
|
||||
- platform `app/`: `features/`, `stores/`, and `shared/` never import it, so `screens/` stays the UI on top.
|
||||
|
||||
## Exports and tree-shaking
|
||||
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ When to refactor:
|
|||
- Before a feature the code resists: reshape the code until the feature is a small, obvious edit, then make that edit.
|
||||
- While fixing a bug, in the layer that owns the fault ([SKILL.md](../SKILL.md#4-workflow)), and only as far as the fix needs.
|
||||
- In review (see Review comments).
|
||||
- At the third duplication, not the second (the rule of three), because by then the copies show what actually varies. island is the exception: a component that needs a second style gets an island variant at once, never a copy ([SKILL.md](../SKILL.md#3-architecture-rules)). A route's organism that a second route needs also moves at once, never as a copy: to island when it's domain-free, or to the nearest route level both share when it knows a domain ([project-structure.md](project-structure.md#choosing-where-a-component-goes)).
|
||||
- At the third duplication, not the second (the rule of three), because by then the copies show what actually varies. island is the exception: a component that needs a second style gets an island variant at once, never a copy ([SKILL.md](../SKILL.md#3-architecture-rules)). A route's organism that a second route needs also moves at once, never as a copy: to island when it's domain-free, or to the platform's `screens/`, at the nearest route level both share, when it knows a domain ([project-structure.md](project-structure.md#choosing-where-a-component-goes)).
|
||||
|
||||
Refactor only the code the change touches, unless the plan says otherwise. Record other smells you notice as debt in the PR's trade-offs note.
|
||||
|
||||
|
|
@ -194,7 +194,7 @@ Grouped as in refactoring.guru's technique catalog. Each line says how the techn
|
|||
- Replace Type Code with Class: a string-literal union in the entity, like `OrderStatus`, or an `as const` object when code needs the values at runtime.
|
||||
- Replace Type Code with Subclasses: a discriminated union with one component per member, chosen through one map.
|
||||
- Replace Type Code with State/Strategy: a discriminated-union status for a flow, and a `Record` of handlers for behavior that varies per member.
|
||||
- Encapsulate Collection: only the store's actions change its arrays. Type the arrays `readonly` in the store's `types.ts`. For the persisted cart store in [code-patterns.md](code-patterns.md#persisted-store), its state becomes the one below. As in code-patterns.md, the path is relative to `platforms/<app>/src/`.
|
||||
- Encapsulate Collection: only the store's actions change its arrays. Type the arrays `readonly` in the store's `types.ts`. For the persisted cart store in [code-patterns.md](code-patterns.md#persisted-store), its state becomes the one below. As in code-patterns.md, the path is relative to `platforms/<platform>/src/`.
|
||||
|
||||
`stores/cart/types.ts`
|
||||
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@ How:
|
|||
- A page that needs a logged-in user, such as every `(account)` page: the route group's layout wraps its children in the platform's `AuthGuard` (`app/guards/auth-guard/`). This client component renders the page skeleton while the status is `'unknown'`, sends a guest to login with a return URL, and renders the page for a member. The page stays a thin Server Component that resolves the device and passes only URL parameters to its template, and the template's parts load in the browser. `generateMetadata` reads no data: it returns a generic title and `robots: { index: false }`.
|
||||
- An action that changes the viewer, such as login, logout, or a payment, updates the auth store, so every auth-dependent part renders its new variant. It doesn't call `router.refresh()`, because no server-rendered content changed.
|
||||
|
||||
`platforms/<app>/src/features/membership/models/product/use-membership-offer-part.ts`. A guest sees an invitation to log in, a member without a subscription sees the subscription offer, and a subscriber (`user.hasSubscription`) sees their benefit. `types.ts` declares `MembershipOfferVariant = 'pending' | 'guest' | 'member' | 'subscriber'`.
|
||||
`platforms/<platform>/src/features/membership/models/product/use-membership-offer-part.ts`. A guest sees an invitation to log in, a member without a subscription sees the subscription offer, and a subscriber (`user.hasSubscription`) sees their benefit. `types.ts` declares `MembershipOfferVariant = 'pending' | 'guest' | 'member' | 'subscriber'`.
|
||||
|
||||
```ts
|
||||
import { useCurrentUser, useViewerStatus } from '../../../../stores/auth';
|
||||
|
|
|
|||
Loading…
Reference in New Issue