Factory AI ESLint Plugin

The @factory/no-use-effect-in-hooks rule prevents the use of effect hooks (any hook ending in effect, such as useEffect, useLayoutEffect, or useMountEffect) inside custom hooks (functions starting with use).

Rationale

Custom hooks are intended to be composable building blocks rather than side-effect containers. This rule enforces better architecture by:

• Making hooks easier to test.
• Ensuring components maintain control over when side effects run.
• Making data flow more explicit and easier to understand.
• Adhering to the principle of least surprise.

Note: This rule does not prevent using effects inside regular React components; it only targets custom hooks.

// Incorrect: Custom hook containing an effect
function useUserData(userId: string) {
  const [user, setUser] = useState(null);

  useEffect(() => {
    fetchUser(userId).then(setUser);
  }, [userId]);

  return user;
}

The @factory/no-exported-string-union-types rule prevents developers from exporting type aliases that consist solely of string literal unions. Instead, it mandates the use of TypeScript enums.

This rule is designed to improve runtime capabilities (iteration and logging), refactoring support, and maintain consistency with file organization patterns (such as using enums.ts).

What is allowed:

• Non-exported string unions (e.g., type Internal = 'a' | 'b';).
• Unions containing non-string types (e.g., type Result = 'success' | number;).
• Unions of other types (e.g., type Nullable<T> = T | null;).

// Correct: Use enums instead
export enum Status {
  Active = 'active',
  Inactive = 'inactive',
  Pending = 'pending',
}

// Correct: Non-exported unions are allowed
type InternalStatus = 'loading' | 'ready';

// Correct: Mixed unions are allowed
export type Result = 'success' | 'error' | number;

// Correct: Unions with other types are allowed
export type Nullable<T> = T | null;

The @factory/test-file-location rule enforces that test files are colocated with the source files they test. This improves developer experience by making tests easy to find and ensuring that moving a source file automatically moves its corresponding tests.

To satisfy this rule, test files must meet three requirements:

1. Naming convention: Files must be named with the .test.ts or .test.tsx suffix.
2. Colocation: Test files must reside in the same directory as the source file they test. They should not be placed in separate test/ or __tests__/ directories.
3. Content: Test files must contain at least one test block (e.g., describe, it, or test).

// Correct: Colocated with source file and contains test blocks
// src/utils/format.ts
// src/utils/format.test.ts
describe('format', () => {
  it('should format dates correctly', () => {
    expect(formatDate(new Date())).toBe('2024-01-01');
  });
});

The @factory/require-tsx-test-stories-files rule enforces that every React component defined in a .tsx file is accompanied by both a unit test file and a Storybook stories file in the same directory. This ensures that components are both logically verified and visually documented.

Requirements

For any non-exempt .tsx file, the following must exist in the same directory:

1. A .test.tsx file (e.g., Component.test.tsx)
2. A .stories.tsx file (e.g., Component.stories.tsx)

Exempt Files

The rule ignores the following files, as they typically do not represent standalone UI components requiring visual documentation:

• Barrel exports: index.tsx
• Next.js App Router files: layout.tsx, page.tsx, loading.tsx, error.tsx, not-found.tsx, template.tsx, default.tsx
• Definition files: types.tsx, constants.tsx, enums.tsx
• Configuration files: style-props.tsx, config.tsx, schema.tsx

// Incorrect
src/components/Button.tsx

// Correct
src/components/Button.tsx
src/components/Button.test.tsx
src/components/Button.stories.tsx

The @factory/require-route-middleware rule enforces that Next.js route handlers in route.ts files call a middleware function as their very first statement. This ensures essential logic like authentication, authorization, logging, and rate limiting is executed before any route-specific logic.

Recognized Middleware Patterns

The rule looks for calls to functions following these naming patterns:

• handleRouteMiddleware
• handleAdminRouteMiddleware
• handleCronMiddleware
• handlePublicMiddleware

Important Exclusions

This rule does not apply to v0 API routes (/api/v0/). For those routes, use the @factory/require-v0-route-handle-middleware rule instead.

// Correct usage: middleware is the first statement
export async function GET(request: Request) {
  return handleRouteMiddleware(request, async () => {
    const data = await fetchData();
    return NextResponse.json(data);
  });
}

The @factory/types-file-organization rule enforces a centralized structure for TypeScript type definitions to prevent type sprawl and improve maintainability.

To comply with this rule, you must follow these three constraints:

1. Location: All exported TypeScript types and interfaces must reside in files named types.ts.
2. Content: Files named types.ts are restricted to containing only type aliases and interface declarations.
3. Imports: Imports within a types.ts file are strictly limited to:
   • External modules
   • Internal enums.ts files
   • Internal types.ts files
   • Internal schema.ts files

// src/types.ts
import { Status } from './enums';
import type { BaseSchema } from './schema';

export interface User {
  id: string;
  name: string;
  status: Status;
}

export type UserId = string;

export type Config = {
  schema: BaseSchema;
  enabled: boolean;
};