Universal Instructions for React / Next.js Projects
# Universal Instructions for React / Next.js Projects > Purpose: General rules for developing various projects with React + TypeScript, Next.js + TypeScript, and Tailwind CSS. > Usage: Place this file in the root of a…
Open the source (opens github.com) https://github.com/f/prompts.chat
What it is
Prompts from Ramazan-Yusupov.
The problem it solves and who it suits haven't been reviewed by InnerVault. The description above is the source's own.
The prompt
# Universal Instructions for React / Next.js Projects
> Purpose: General rules for developing various projects with React + TypeScript, Next.js + TypeScript, and Tailwind CSS.
> Usage: Place this file in the root of a new project as `AGENTS.md`, `CLAUDE.md`, or `PROJECT_RULES.md`, or use it as a base instruction set for an AI agent.
> Important: These instructions do not contain product-specific rules. Keep everything related to an individual project in a separate `PROJECT_RULES.md` file.
---
# 1. Core Principle
Build a production-ready application, not a collection of disconnected components.
Always follow this sequence:
1. Review the current project structure, `package.json`, routing, UI primitives, stores, hooks, schemas, and project rules.
2. Find existing actions, helpers, schemas, and components that can be reused.
3. Identify the smallest change required for the task.
4. Preserve existing behavior.
5. Implement each new feature end to end: model, validation, UI, storage/import/export, edge cases, and verification.
6. Run the relevant checks and report the results honestly.
Do not add dependencies, abstractions, a global store, or an architectural layer unless they are genuinely necessary.
Use `shadcn/ui` by default for UI work. Do not add another UI kit on top of it without a clear reason.
---
# 2. Choosing Between React and Next.js
Use Next.js when the project needs:
- routing;
- SEO;
- SSR / Server Components;
- Server Actions;
- Route Handlers / API routes;
- authentication;
- database access;
- private environment variables;
- content publishing.
Use React + Vite when:
- the application is entirely client-side;
- SEO is not required;
- it is a local tool, dashboard, editor, admin panel, or desktop-like UI;
- the server already exists as a separate service.
Do not choose Next.js simply because it is popular. Do not add Redux, Zustand, React Query, a form library, or another UI kit without a specific reason.
---
# 3. Default Stack and Checks
Use the following by default:
- React;
- TypeScript in strict mode;
- Tailwind CSS;
- `shadcn/ui` as the required UI approach for clean design and rapid interface development;
- Lucide React or the icon library used by the current shadcn configuration;
- ESLint;
- a shared `cn()` helper;
- runtime validation for external data;
- accessible HTML elements.
Use `shadcn/ui` as the primary source of UI primitives: buttons, inputs, selects, dialogs, sheets, dropdowns, tooltips, tabs, carousels, cards, badges, skeletons, scroll areas, and other required components. Create custom primitives only when shadcn does not provide a suitable component or when the project already has a stable local primitive.
For an MVP, begin with mock/JSON/localStorage data and validate local user flows first. Add the backend, database, payments, authentication, and external integrations last, once the UI, models, and flows are clear.
At a minimum, run these commands after code changes:
```bash
npm run typecheck
npm run lint
npm run build
```
Do not claim that the project works if these commands were not run or completed with errors.
---
# 4. Architecture
For Next.js projects expected to grow, keep source code inside `src/` by default: `src/app`, `src/components`, `src/lib`, `src/data`, `src/hooks`, and `src/features`. Keep root-level support folders and files (`public`, configuration files, lockfiles, and README) in the project root.
For small projects, the following structure is acceptable:
```text
src/
app/ or pages/
components/
features/
lib/
shared/
```
For medium and large projects, use an FSD-like approach:
```text
src/
app/ # bootstrap, providers, layouts, routes
views/ # page-level composition
widgets/ # large UI blocks
features/ # user workflows
entities/ # domain model
shared/ # generic helpers, config, thin wrappers around shadcn/ui
```
Import direction:
```text
app/views -> widgets -> features -> entities -> shared
```
Do not:
- import `widgets` into `features`;
- place business logic in `shared`;
- turn `shared/lib` into a dumping ground for unrelated functions;
- duplicate mutation logic across multiple UI components;
- use deep imports into another module's internals when that module exposes a public API.
---
# 5. Public API
Every feature, entity, or shared UI folder should expose a clear public API through `index.ts` when the module is used externally. For shadcn primitives, the public API usually already lives in `components/ui/*` or the project's local UI layer.
Good:
```ts
import { createTask } from "@/features/create-task";
```
Bad:
```ts
import { createTask } from "@/features/create-task/model/createTask";
```
Exception: internal code within the same feature or entity.
---
# 6. TypeScript
Required:
- enable `strict: true`;
- do not use `any` except in isolated interoperability code;
- do not hide type errors with `as` assertions;
- use discriminated unions for complex state;
- validate runtime JSON with a schema;
- do not create multiple identical types without a meaningful reason.
Example state type:
```ts
type LoadState<T> =
| { status: "idle" }
| { status: "loading" }
| { status: "success"; data: T }
| { status: "error"; message: string };
```
---
# 7. React State and Effects
Store state where it actually belongs:
| State type | Where to store it |
| ------------ | ----------------------------------------------------------- |
| Local UI | `useState`, `useReducer` |
| URL state | route/search parameters |
| Server state | server rendering or a cache/query layer |
| Form state | form hook/library |
| Global UI | a small store when necessary |
| Domain state | entity/store when the state is shared across multiple flows |
Do not put…
Written by the prompts.chat (CC0 prompt collection) community (Ramazan-Yusupov). Not tested by InnerVault.
How to get it
Setup steps: not applicable.
Related
-
# **🔥 Universal Lead & Candidate Outreach Generator** ### *AI Prompt for Automated Message Creation from LinkedIn JSON + PDF Offers* --- ## **🚀 Global Instruction for the Chatbot** You are an AI assistant specialized…
-
{ "subject": { "description": "A cheerful university student studying at home, captured during a casual study session. Her hair is messy and unstyled, giving a natural, lived-in student look, but her expression is…
-
Stylelint Plugin Author
Prompts--- name: "Copilot-Instructions-Stylelint-Plugin" description: "Instructions for the expert TypeScript + PostCSS AST + Stylelint Plugin architect." applyTo: "**" --- <instructions> <role> ## Your Role, Goal, and…
-
Act as an Organizational Structure and Workflow Design Expert. You are responsible for creating detailed organizational charts and workflows for various departments at Giresun University, such as faculties, vocational…
-
Act as an Academic Writing Assistant. You are an expert in crafting well-structured and researched university-level assignments. Your task is to help students by generating content that can be directly copied into…
-
Summarize and export all important points, instructions, and contextual information exchanged in this chat, structured per your requirements. - Use section headers for each major category (e.g., Task Instructions…