@yousxlfs/next-arch 0.1.1 → 0.2.0

package/templates/packages/tanstack-form/examples/src/features/_examples/with-tanstack-form/components/ExampleForm.tsx

@@ -0,0 +1,60 @@
+'use client';
+
+/**
+ * ПРИМЕР: TanStack Form + Zod в фиче
+ *
+ * Где живёт: features/<name>/components/ (или ui/)
+ * Форма — UI с логикой ввода, принадлежит фиче.
+ * Схема валидации — entities/<entity>/lib/ или types/ фичи.
+ */
+
+import { useForm } from '@tanstack/react-form';
+import { z } from 'zod';
+
+const exampleSchema = z.object({
+  email: z.string().email('Некорректный email'),
+  password: z.string().min(8, 'Минимум 8 символов'),
+});
+
+type ExampleFormValues = z.infer<typeof exampleSchema>;
+
+export function ExampleForm() {
+  const form = useForm({
+    defaultValues: { email: '', password: '' } satisfies ExampleFormValues,
+    onSubmit: async ({ value }) => {
+      const parsed = exampleSchema.safeParse(value);
+      if (!parsed.success) return;
+      // Вызов Server Action из features/<name>/actions/
+      console.log(parsed.data);
+    },
+  });
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        void form.handleSubmit();
+      }}
+      className="flex flex-col gap-4 max-w-sm"
+    >
+      <form.Field name="email">
+        {(field) => (
+          <label className="flex flex-col gap-1 text-sm">
+            Email
+            <input
+              className="rounded border px-3 py-2"
+              value={field.state.value}
+              onChange={(e) => field.handleChange(e.target.value)}
+            />
+          </label>
+        )}
+      </form.Field>
+      <button type="submit" className="rounded bg-primary px-4 py-2 text-primary-foreground">
+        Отправить
+      </button>
+    </form>
+  );
+}
+
+// Куда это идёт в архитектуре:
+// features/<name>/components/ — UI фичи. View импортирует форму через @/features/<name>.

package/templates/packages/tanstack-query/core/src/shared/lib/query-client.ts

@@ -0,0 +1,24 @@
+/**
+ * ПРИМЕР: глобальный QueryClient для TanStack Query
+ *
+ * Где живёт: shared/lib/
+ * Почему здесь: QueryClient — инфраструктура, не бизнес-логика.
+ * Один экземпляр на всё приложение, переиспользуется всеми фичами.
+ *
+ * Правило: фичи импортируют queryClient отсюда, но queries/mutations
+ * объявляют внутри своей фичи (features/<name>/queries/).
+ */
+
+import { QueryClient } from '@tanstack/react-query';
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60 * 1000,
+      refetchOnWindowFocus: false,
+    },
+  },
+});
+
+// Куда это идёт в архитектуре:
+// shared/lib/ — слой shared, доступен всем верхним слоям (entities → features → views → app).

package/templates/packages/tanstack-query/core/src/shared/providers/QueryProvider.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+/**
+ * ПРИМЕР: провайдер TanStack Query для Next.js App Router
+ *
+ * Где живёт: shared/providers/
+ * Почему здесь: провайдер — инфраструктурная обёртка, не привязана к фиче.
+ * Подключается один раз в app/layout.tsx.
+ */
+
+import { QueryClientProvider } from '@tanstack/react-query';
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
+import type { ReactNode } from 'react';
+import { queryClient } from '@/shared/lib/query-client';
+
+interface QueryProviderProps {
+  children: ReactNode;
+}
+
+export function QueryProvider({ children }: QueryProviderProps) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  );
+}
+
+// Куда это идёт в архитектуре:
+// shared/providers/ → импортируется в app/layout.tsx (слой app, только композиция).

package/templates/packages/tanstack-query/examples/src/features/_examples/with-tanstack-query/README.md

@@ -0,0 +1,34 @@
+# Пример: TanStack Query
+
+Папку `_examples` можно удалить после изучения.
+
+## Структура
+
+- `queries/` — клиентские хуки с кешем (`useQuery`, `useMutation`)
+- `actions/` — Server Actions, источник данных на сервере
+
+## Как перенести в свою фичу
+
+```bash
+npx @yousxlfs/next-arch g feature billing
+```
+
+Скопируй паттерн в `src/features/billing/queries/` и `actions/`.
+
+## Подключение провайдера
+
+В `src/app/layout.tsx`:
+
+```tsx
+import { QueryProvider } from '@/shared/providers/QueryProvider';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <QueryProvider>{children}</QueryProvider>
+      </body>
+    </html>
+  );
+}
+```

package/templates/packages/tanstack-query/examples/src/features/_examples/with-tanstack-query/actions/example.action.ts

@@ -0,0 +1,34 @@
+'use server';
+
+/**
+ * ПРИМЕР: Server Action как источник данных для TanStack Query
+ *
+ * Где живёт: features/<name>/actions/
+ * Почему здесь: actions выполняются на сервере (мутации, fetch с секретами).
+ * Query-хук в queries/ вызывает action и кеширует результат на клиенте.
+ *
+ * Правило: не импортируй server actions напрямую в UI-компоненты для чтения —
+ * оборачивай в useQuery/useMutation.
+ */
+
+export interface ExampleData {
+  id: string;
+  title: string;
+}
+
+export async function fetchExampleAction(): Promise<
+  { ok: true; data: ExampleData } | { ok: false; error: string }
+> {
+  // В реальном проекте здесь будет запрос к БД или внешнему API
+  return {
+    ok: true,
+    data: {
+      id: '1',
+      title: 'Пример данных с сервера',
+    },
+  };
+}
+
+// Куда это идёт в архитектуре:
+// features/<name>/actions/ — серверный слой фичи.
+// Вызывается из queries/ той же фичи, не из views/ напрямую.

package/templates/packages/tanstack-query/examples/src/features/_examples/with-tanstack-query/queries/use-example.query.ts

@@ -0,0 +1,49 @@
+'use client';
+
+/**
+ * ПРИМЕР: TanStack Query в архитектуре next-arch
+ *
+ * Где живёт: features/<name>/queries/
+ * Почему здесь: queries — клиентский кеш серверных данных.
+ * Они принадлежат конкретной фиче и не выносятся в shared/.
+ *
+ * Правило: Server Actions делают мутации (actions/),
+ * TanStack Query кеширует и синхронизирует данные (queries/).
+ * Никогда не смешивай их ответственности.
+ */
+
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { fetchExampleAction } from '../actions/example.action';
+
+const EXAMPLE_QUERY_KEY = ['example'] as const;
+
+export function useExampleQuery() {
+  return useQuery({
+    queryKey: EXAMPLE_QUERY_KEY,
+    queryFn: async () => {
+      const result = await fetchExampleAction();
+      if (!result.ok) {
+        throw new Error(result.error);
+      }
+      return result.data;
+    },
+  });
+}
+
+export function useExampleMutation() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (message: string) => {
+      return { message, updatedAt: new Date().toISOString() };
+    },
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: EXAMPLE_QUERY_KEY });
+    },
+  });
+}
+
+// Куда это идёт в архитектуре:
+// features/_examples/with-tanstack-query/queries/ — клиентский слой фичи.
+// Импортирует action из ../actions/ (та же фича, относительный путь — OK).
+// В реальном проекте замени _examples на свою фичу, например features/billing/queries/.

package/templates/packages/tanstack-table/examples/src/features/_examples/with-tanstack-table/README.md

@@ -0,0 +1,3 @@
+# Пример: TanStack Table
+
+Headless UI — стилизуй через Tailwind в components/ фичи.

package/templates/packages/tanstack-table/examples/src/features/_examples/with-tanstack-table/components/ExampleTable.tsx

@@ -0,0 +1,66 @@
+'use client';
+
+/**
+ * ПРИМЕР: TanStack Table (headless)
+ *
+ * Где живёт: features/<name>/components/
+ * Таблица — UI фичи, данные приходят из queries/ или props от view.
+ */
+
+import {
+  createColumnHelper,
+  flexRender,
+  getCoreRowModel,
+  useReactTable,
+} from '@tanstack/react-table';
+
+interface Row {
+  id: string;
+  name: string;
+}
+
+const columnHelper = createColumnHelper<Row>();
+
+const columns = [
+  columnHelper.accessor('id', { header: 'ID' }),
+  columnHelper.accessor('name', { header: 'Name' }),
+];
+
+const data: Row[] = [
+  { id: '1', name: 'Пример' },
+  { id: '2', name: 'Строка' },
+];
+
+export function ExampleTable() {
+  const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
+
+  return (
+    <table className="w-full border-collapse text-sm">
+      <thead>
+        {table.getHeaderGroups().map((hg) => (
+          <tr key={hg.id}>
+            {hg.headers.map((header) => (
+              <th key={header.id} className="border px-3 py-2 text-left">
+                {flexRender(header.column.columnDef.header, header.getContext())}
+              </th>
+            ))}
+          </tr>
+        ))}
+      </thead>
+      <tbody>
+        {table.getRowModel().rows.map((row) => (
+          <tr key={row.id}>
+            {row.getVisibleCells().map((cell) => (
+              <td key={cell.id} className="border px-3 py-2">
+                {flexRender(cell.column.columnDef.cell, cell.getContext())}
+              </td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+// Куда это идёт в архитектуре:
+// features/<name>/components/ — не в shared/, таблица привязана к домену фичи.

package/templates/packages/trpc/core/src/app/api/trpc/router.ts

@@ -0,0 +1,19 @@
+/**
+ * ПРИМЕР: tRPC router (заглушка)
+ *
+ * Где живёт: app/api/trpc/ или отдельный backend.
+ * В FSD клиентские хуки tRPC — в features/<name>/queries/.
+ */
+
+import { initTRPC } from '@trpc/server';
+
+const t = initTRPC.create();
+
+export const appRouter = t.router({
+  hello: t.procedure.query(() => ({ message: 'Привет из tRPC' })),
+});
+
+export type AppRouter = typeof appRouter;
+
+// Куда это идёт в архитектуре:
+// Серверный роутер — app/api или packages/server. Не в shared/.

package/templates/packages/trpc/examples/src/app/providers/trpc-client.ts

@@ -0,0 +1,13 @@
+'use client';
+
+/**
+ * ПРИМЕР: tRPC React client
+ *
+ * Где живёт: app/providers/
+ * app — верхний слой, может импортировать типы роутера из app/api/.
+ */
+
+import { createTRPCReact } from '@trpc/react-query';
+import type { AppRouter } from '@/app/api/trpc/router';
+
+export const trpc = createTRPCReact<AppRouter>();

package/templates/packages/uploadthing/core/src/app/api/uploadthing/route.ts

@@ -0,0 +1,10 @@
+/**
+ * ПРИМЕР: Uploadthing — route handler
+ *
+ * Где живёт: app/api/uploadthing/
+ */
+
+// import { createRouteHandler } from 'uploadthing/next';
+// export const { GET, POST } = createRouteHandler({ router: uploadRouter });
+
+export const UPLOADTHING_PLACEHOLDER = 'Создай uploadRouter в features/<name>/lib/';

package/templates/packages/zustand/core/src/shared/lib/store.ts

@@ -0,0 +1,13 @@
+/**
+ * ПРИМЕР: где держать Zustand
+ *
+ * Бизнес-стейт → features/<name>/model/
+ * Глобальный UI (тема, sidebar) → можно здесь в shared/lib/, если не привязан к фиче.
+ *
+ * См. пример store в src/features/_examples/with-zustand/model/example.store.ts
+ */
+
+export {};
+
+// Куда это идёт в архитектуре:
+// shared/lib/ — только инфраструктура без бизнес-логики фич.

package/templates/packages/zustand/examples/src/features/_examples/with-zustand/README.md

@@ -0,0 +1,13 @@
+# Пример: Zustand
+
+Store живёт в `model/` внутри фичи, не в `shared/`.
+
+## Публичный API
+
+Добавь в `features/<name>/index.ts`:
+
+```ts
+export { useUiStore } from './model/example.store';
+```
+
+Views импортируют только через `@/features/<name>`.

package/templates/packages/zustand/examples/src/features/_examples/with-zustand/model/example.store.ts

@@ -0,0 +1,28 @@
+'use client';
+
+/**
+ * ПРИМЕР: Zustand store внутри фичи
+ *
+ * Где живёт: features/<name>/model/
+ * Почему здесь: стейт принадлежит фиче. Другие фичи не импортируют этот store
+ * напрямую — используй shared/ или прокидывай данные через props из view.
+ *
+ * Правило next-arch/no-cross-feature-imports: features/cart не импортирует
+ * features/auth/model/*.store.ts. Вынеси общее в entities/ или shared/.
+ */
+
+import { create } from 'zustand';
+
+interface UiState {
+  sidebarOpen: boolean;
+  toggleSidebar: () => void;
+}
+
+export const useUiStore = create<UiState>((set) => ({
+  sidebarOpen: true,
+  toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
+}));
+
+// Куда это идёт в архитектуре:
+// features/<name>/model/ — клиентский стейт конкретной фичи.
+// Экспортируй через features/<name>/index.ts для views/.

package/templates/pages/auth/src/app/({{name}})/layout.tsx

@@ -0,0 +1,7 @@
+export default function {{Name}}Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-muted/30 p-4">
+      {children}
+    </div>
+  );
+}

package/templates/pages/auth/src/app/({{name}})/login/page.tsx

@@ -0,0 +1,5 @@
+import { LoginView } from '@/views/{{name}}';
+
+export default function LoginPage() {
+  return <LoginView />;
+}

package/templates/pages/auth/src/app/({{name}})/register/page.tsx

@@ -0,0 +1,5 @@
+import { RegisterView } from '@/views/{{name}}';
+
+export default function RegisterPage() {
+  return <RegisterView />;
+}

package/templates/pages/auth/src/entities/user/index.ts

@@ -0,0 +1,2 @@
+export type { User } from './types/user.types';
+export { userSchema, type UserSchema } from './lib/user-schema';

package/templates/pages/auth/src/entities/user/lib/user-schema.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+
+export const userSchema = z.object({
+  id: z.string(),
+  email: z.string().email(),
+  name: z.string().min(1),
+});
+
+export type UserSchema = z.infer<typeof userSchema>;

package/templates/pages/auth/src/entities/user/types/user.types.ts

@@ -0,0 +1,5 @@
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+}

package/templates/pages/auth/src/features/{{name}}/actions/login.action.ts

@@ -0,0 +1,7 @@
+'use server';
+
+import type { LoginInput } from '../types/auth.types';
+
+export async function loginAction(input: LoginInput) {
+  return { ok: true as const, userId: 'demo', email: input.email };
+}

package/templates/pages/auth/src/features/{{name}}/actions/logout.action.ts

@@ -0,0 +1,5 @@
+'use server';
+
+export async function logoutAction() {
+  return { ok: true as const };
+}

package/templates/pages/auth/src/features/{{name}}/actions/register.action.ts

@@ -0,0 +1,7 @@
+'use server';
+
+import type { RegisterInput } from '../types/auth.types';
+
+export async function registerAction(input: RegisterInput) {
+  return { ok: true as const, userId: 'demo', email: input.email };
+}

package/templates/pages/auth/src/features/{{name}}/components/AuthGuard.tsx

@@ -0,0 +1,14 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { useSession } from '../hooks/use-session';
+
+interface AuthGuardProps {
+  children: ReactNode;
+  fallback?: ReactNode;
+}
+
+export function AuthGuard({ children, fallback = <p>Требуется авторизация</p> }: AuthGuardProps) {
+  const { isAuthenticated } = useSession();
+  return isAuthenticated ? children : fallback;
+}

package/templates/pages/auth/src/features/{{name}}/components/LoginForm.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import { useState } from 'react';
+import { loginAction } from '../actions/login.action';
+
+export function LoginForm() {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+
+  return (
+    <form
+      className="flex flex-col gap-3"
+      onSubmit={(e) => {
+        e.preventDefault();
+        void loginAction({ email, password });
+      }}
+    >
+      <input
+        className="rounded border px-3 py-2"
+        placeholder="Email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+      />
+      <input
+        className="rounded border px-3 py-2"
+        type="password"
+        placeholder="Пароль"
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+      />
+      <button type="submit" className="rounded bg-primary px-4 py-2 text-primary-foreground">
+        Войти
+      </button>
+    </form>
+  );
+}

package/templates/pages/auth/src/features/{{name}}/components/RegisterForm.tsx

@@ -0,0 +1,43 @@
+'use client';
+
+import { useState } from 'react';
+import { registerAction } from '../actions/register.action';
+
+export function RegisterForm() {
+  const [name, setName] = useState('');
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+
+  return (
+    <form
+      className="flex flex-col gap-3"
+      onSubmit={(e) => {
+        e.preventDefault();
+        void registerAction({ name, email, password });
+      }}
+    >
+      <input
+        className="rounded border px-3 py-2"
+        placeholder="Имя"
+        value={name}
+        onChange={(e) => setName(e.target.value)}
+      />
+      <input
+        className="rounded border px-3 py-2"
+        placeholder="Email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+      />
+      <input
+        className="rounded border px-3 py-2"
+        type="password"
+        placeholder="Пароль"
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+      />
+      <button type="submit" className="rounded bg-primary px-4 py-2 text-primary-foreground">
+        Зарегистрироваться
+      </button>
+    </form>
+  );
+}

package/templates/pages/auth/src/features/{{name}}/hooks/use-session.ts

@@ -0,0 +1,14 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import type { Session } from '../types/auth.types';
+
+export function useSession() {
+  const [session, setSession] = useState<Session | null>(null);
+
+  const setDemoSession = useCallback((value: Session | null) => {
+    setSession(value);
+  }, []);
+
+  return { session, setDemoSession, isAuthenticated: Boolean(session) };
+}

package/templates/pages/auth/src/features/{{name}}/index.ts

@@ -0,0 +1,9 @@
+export { LoginForm } from './components/LoginForm';
+export { RegisterForm } from './components/RegisterForm';
+export { AuthGuard } from './components/AuthGuard';
+export { useSession } from './hooks/use-session';
+export { useUserQuery } from './queries/use-user.query';
+export { loginAction } from './actions/login.action';
+export { registerAction } from './actions/register.action';
+export { logoutAction } from './actions/logout.action';
+export type { LoginInput, RegisterInput, Session } from './types/auth.types';

package/templates/pages/auth/src/features/{{name}}/lib/auth-helpers.ts

@@ -0,0 +1,3 @@
+export function isValidEmail(email: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}

package/templates/pages/auth/src/features/{{name}}/queries/use-user.query.ts

@@ -0,0 +1,16 @@
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import { loginAction } from '../actions/login.action';
+
+export function useUserQuery(email: string | null) {
+  return useQuery({
+    queryKey: ['user', email],
+    enabled: Boolean(email),
+    queryFn: async () => {
+      if (!email) return null;
+      const result = await loginAction({ email, password: 'demo' });
+      return result.ok ? result : null;
+    },
+  });
+}

package/templates/pages/auth/src/features/{{name}}/types/auth.types.ts

@@ -0,0 +1,13 @@
+export interface LoginInput {
+  email: string;
+  password: string;
+}
+
+export interface RegisterInput extends LoginInput {
+  name: string;
+}
+
+export interface Session {
+  userId: string;
+  email: string;
+}

package/templates/pages/auth/src/views/{{name}}/LoginView.tsx

@@ -0,0 +1,10 @@
+import { LoginForm } from '@/features/{{name}}';
+
+export function LoginView() {
+  return (
+    <main className="w-full max-w-md space-y-4 rounded-xl border bg-card p-8 shadow-sm">
+      <h1 className="text-2xl font-semibold">Вход</h1>
+      <LoginForm />
+    </main>
+  );
+}