@reasonabletech/eslint-config 0.1.0 → 0.2.1

package/docs/reference/frameworks/README.md

@@ -0,0 +1,61 @@
+# Framework Configurations
+
+Framework-specific ESLint configurations with specialized rules and patterns.
+
+## Overview
+
+This section provides detailed documentation for framework-specific ESLint configurations, including React, Next.js, and other popular development frameworks supported by `@reasonabletech/eslint-config`.
+
+## Available Frameworks
+
+### React
+
+- **[React Configuration](./react-config.md)** - ESLint rules for React component development with hooks support
+
+### Next.js
+
+- **[Next.js Configuration](./next-config.md)** - Full-stack React applications with server actions and app router
+
+## Framework Selection Guide
+
+### Choose React Configuration When
+
+- Building React libraries or component packages
+- Creating client-side React applications
+- Working with React Native projects
+- Developing Storybook components
+
+### Choose Next.js Configuration When
+
+- Building Next.js applications with app router
+- Using Next.js server actions and server components
+- Implementing Next.js API routes
+- Deploying full-stack React applications
+
+## Configuration Features
+
+Each framework configuration includes:
+
+- **Base type-aware rules** from the core configuration
+- **Framework-specific plugins** and their recommended rules
+- **Custom rule overrides** for framework patterns
+- **Specialized globals** for the framework environment
+- **Performance optimizations** for the specific build tool
+
+## Usage Patterns
+
+All framework configurations follow the same usage pattern:
+
+```typescript
+// Framework-specific import
+import { createTypeAware[Framework]Config } from "@reasonabletech/eslint-config/[framework]";
+
+// Project directory configuration
+export default createTypeAware[Framework]Config(import.meta.dirname);
+```
+
+## Related Documentation
+
+- [API Reference](../api-reference.md) - Complete function documentation
+- [Usage Guide](../../guides/usage-guide.md) - Setup instructions and examples
+- [Architecture](../../concepts/architecture.md) - Framework integration design decisions

package/docs/reference/frameworks/next-config.md

@@ -0,0 +1,187 @@
+# Next.js ESLint Configuration
+
+The Next.js configuration (`@reasonabletech/eslint-config/next`) provides comprehensive TypeScript, React, and Next.js rules specifically tailored for Next.js applications in the monorepo.
+
+## Features
+
+- **Complete TypeScript integration**: All base TypeScript type-aware rules included
+- **Comprehensive React support**: Full React configuration with hooks validation
+- **Next.js optimization**: Core web vitals and Next.js-specific performance rules
+- **Graceful fallbacks**: Automatic React setup when Next.js plugins unavailable
+- **Smart ignore patterns**: Optimized file exclusions for Next.js build outputs
+- **Modular architecture**: Built from focused, reusable modules with shared React rules
+
+## Installation
+
+This package is installed as a workspace dependency:
+
+```bash
+pnpm add -D @reasonabletech/eslint-config
+```
+
+## Usage
+
+Create an `eslint.config.mjs` file in your project root:
+
+```javascript
+// eslint.config.mjs
+import { createTypeAwareNextConfig } from "@reasonabletech/eslint-config/next";
+
+export default createTypeAwareNextConfig(import.meta.dirname);
+```
+
+## Configuration Details
+
+The Next.js configuration automatically includes the complete TypeScript base configuration plus React-specific enhancements and Next.js-specific optimizations:
+
+### Base TypeScript Features
+
+- Full type-aware analysis with TypeScript's type checker
+- **Strict boolean expressions enforced** - explicit checks required even in Next.js
+- JSDoc documentation requirements
+- Performance-optimized type checking
+
+### React Integration
+
+- Complete React plugin setup with hooks validation
+- Modern JSX transform support (no React imports needed)
+- Browser and service worker globals configured
+- **TypeScript rule adjustments** for React patterns while maintaining strict safety
+
+### Next.js-Specific Features
+
+#### Core Web Vitals & Performance
+
+- Next.js `core-web-vitals` rules via `@next/eslint-plugin-next`
+- Performance optimization rules for images, scripts, and routing
+- Server-side rendering and hydration safety checks
+
+#### Smart File Ignores
+
+- Build outputs: `.next/`, `out/`, `dist/`, `build/`
+- Generated files: `next-env.d.ts`, `next.config.*`
+- Development files: Storybook, test files, config files
+- Next.js app directory patterns: `app/.well-known/**/*`
+
+#### Graceful Plugin Loading
+
+- **Primary**: Uses Next.js ESLint configs when available
+- **Fallback**: Automatic React setup when Next.js plugins unavailable
+- **Environment-aware**: Adapts to different development environments
+
+### Important: Strict Boolean Expressions in Next.js
+
+Like React configuration, Next.js enforces strict boolean expressions to prevent rendering bugs and maintain architectural consistency.
+
+#### ❌ Problematic Next.js Patterns
+
+```tsx
+// These patterns violate strict-boolean-expressions
+{
+  params.id && <UserPage userId={params.id} />;
+} // Could render "0"
+{
+  searchParams?.q && <SearchResults query={searchParams.q} />;
+} // Could render empty string
+{
+  session.user && <UserMenu user={session.user} />;
+} // Could render [object Object]
+```
+
+#### ✅ Correct Next.js Patterns
+
+```tsx
+// Explicit checks prevent rendering bugs
+{
+  params.id != null && <UserPage userId={params.id} />;
+}
+{
+  (searchParams?.q?.length ?? 0) > 0 && (
+    <SearchResults query={searchParams.q} />
+  );
+}
+{
+  session.user != null && <UserMenu user={session.user} />;
+}
+
+// Next.js-specific patterns
+{
+  Boolean(params.slug) && <DynamicPage slug={params.slug} />;
+}
+{
+  searchParams != null && Object.keys(searchParams).length > 0 && (
+    <FilteredView />
+  );
+}
+```
+
+## Example with Custom Rules
+
+```javascript
+// eslint.config.js
+import { config as nextConfig } from "@reasonabletech/eslint-config/next";
+
+export default [
+  ...nextConfig,
+  {
+    // Page component rules
+    files: ["**/pages/**/*.{tsx,jsx}"],
+    rules: {
+      // Enforce Next.js page conventions
+      "@next/next/no-document-import-in-page": "error",
+      "@next/next/no-head-import-in-document": "error",
+    },
+  },
+  {
+    // API route rules
+    files: ["**/pages/api/**/*.{ts,js}"],
+    rules: {
+      // Enforce API route best practices
+      "@next/next/no-html-link-for-pages": "error",
+    },
+  },
+];
+```
+
+## Next.js App Directory Structure
+
+When working with Next.js App Directory:
+
+```javascript
+// eslint.config.js
+import { config as nextConfig } from "@reasonabletech/eslint-config/next";
+
+export default [
+  ...nextConfig,
+  {
+    // App directory client components
+    files: ["**/app/**/page.{tsx,jsx}", "**/app/**/layout.{tsx,jsx}"],
+    rules: {
+      // Rules specific to page/layout components
+      "@next/next/no-sync-scripts": "error",
+    },
+  },
+  {
+    // Route handlers
+    files: ["**/app/api/**/route.{ts,js}"],
+    rules: {
+      // Rules specific to API routes
+      "no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
+    },
+  },
+];
+```
+
+## Best Practices
+
+- Use this configuration for all Next.js applications
+- Configure different rules for pages vs. API routes
+- For the App Directory, consider separate rules for server vs. client components
+- Follow Next.js best practices for optimizing core web vitals
+
+## Related Documentation
+
+- [React Configuration](./react-config.md) — React specific configuration (Next.js builds on this)
+- [API Reference](../api-reference.md) — Complete function documentation
+- [Usage Guide](../../guides/usage-guide.md) — Setup instructions and troubleshooting
+- [AI Code Safety](../../concepts/ai-code-safety.md) — Why strict linting matters

package/docs/reference/frameworks/react-config.md

@@ -0,0 +1,273 @@
+# React ESLint Configuration
+
+The React configuration (`@reasonabletech/eslint-config/react`) provides comprehensive TypeScript and React rules specifically tailored for React projects in the monorepo.
+
+## Features
+
+- **Complete TypeScript integration**: All base TypeScript type-aware rules included
+- **Modern React support**: React 18+ with new JSX transform compatibility
+- **React Hooks validation**: Exhaustive dependency checking and Rules of Hooks
+- **Browser environment**: Browser and service worker globals configured
+- **Optimized rule sets**: React-specific TypeScript rule adjustments
+- **Modular architecture**: Built from focused, reusable modules
+
+## Installation
+
+This package is installed as a workspace dependency:
+
+```bash
+pnpm add -D @reasonabletech/eslint-config
+```
+
+## Usage
+
+Create an `eslint.config.mjs` file in your project root:
+
+```javascript
+// eslint.config.mjs
+import { createTypeAwareReactConfig } from "@reasonabletech/eslint-config/react";
+
+export default createTypeAwareReactConfig(import.meta.dirname);
+```
+
+## Configuration Details
+
+The React configuration automatically includes the complete TypeScript base configuration plus React-specific enhancements:
+
+### Base TypeScript Features
+
+- Full type-aware analysis with TypeScript's type checker
+- Strict type safety rules optimized for AI-generated code
+- JSDoc documentation requirements
+- Performance-optimized type checking
+
+### React-Specific Additions
+
+#### Plugins & Rules
+
+- **React Plugin**: Core React linting with `eslint-plugin-react`
+- **React Hooks Plugin**: Rules of Hooks and exhaustive dependency validation
+- **Modern JSX**: `react/react-in-jsx-scope` disabled for new JSX transform
+
+#### Environment Configuration
+
+- **Browser Globals**: Complete browser API support
+- **Service Worker Globals**: PWA and service worker compatibility
+- **React Settings**: Automatic React version detection
+
+#### TypeScript Rule Adjustments
+
+- `@typescript-eslint/prefer-readonly-parameter-types`: Disabled for component props
+- `@typescript-eslint/require-await`: Disabled for event handlers
+- `@typescript-eslint/unbound-method`: Disabled for React patterns
+- **`@typescript-eslint/strict-boolean-expressions`: ENABLED** - Explicit boolean checks required even in React
+
+#### JSDoc Rules
+
+- Component files (`.tsx`, `.jsx`) exempt from `@returns` documentation
+- TypeScript provides return type information automatically
+
+## Conditional Rendering with Strict Boolean Expressions
+
+The React configuration enforces explicit boolean checks in conditional rendering to prevent common bugs and maintain architectural consistency. This means **truthiness checks are not allowed** - you must be explicit about your conditions.
+
+### ❌ Problematic Patterns (Will Cause Lint Errors)
+
+```tsx
+// These patterns can render unexpected values like 0, "", or "[object Object]"
+{
+  items && <ItemList items={items} />;
+} // Could render empty array or 0
+{
+  count && <Counter value={count} />;
+} // Will render 0 instead of nothing
+{
+  user?.name && <UserName name={user.name} />;
+} // Could render empty string
+{
+  error && <ErrorMessage>{error}</ErrorMessage>;
+} // Could render error object
+```
+
+### ✅ Correct Patterns (Explicit Boolean Checks)
+
+```tsx
+// Arrays - check length explicitly
+{
+  items.length > 0 && <ItemList items={items} />;
+}
+
+// Numbers - explicit comparison
+{
+  count > 0 && <Counter value={count} />;
+}
+
+// Strings - null check or length check
+{
+  user?.name != null && <UserName name={user.name} />;
+}
+{
+  (user?.name?.length ?? 0) > 0 && <UserName name={user.name} />;
+}
+
+// Objects - explicit null/undefined checks
+{
+  error != null && <ErrorMessage>{error}</ErrorMessage>;
+}
+{
+  selectedWorkspace != null && (
+    <WorkspaceOverview workspace={selectedWorkspace} />
+  );
+}
+
+// Boolean conversion when appropriate
+{
+  Boolean(user?.name) && <UserName name={user.name} />;
+}
+
+// Multiple conditions
+{
+  user != null && user.isActive && <ActiveUserBadge />;
+}
+```
+
+### Advanced Patterns
+
+#### Guard Components
+
+For complex conditions, use guard components:
+
+```tsx
+function ConditionalRenderer({
+  condition,
+  children,
+}: {
+  condition: boolean;
+  children: React.ReactNode;
+}) {
+  return condition ? <>{children}</> : null;
+}
+
+// Usage
+<ConditionalRenderer condition={items.length > 0}>
+  <ItemList items={items} />
+</ConditionalRenderer>;
+```
+
+#### Custom Hooks for State Logic
+
+```tsx
+function useVisibilityState(items: unknown[]) {
+  return {
+    shouldShowList: items.length > 0,
+    shouldShowEmptyState: items.length === 0,
+  };
+}
+
+// Usage in component
+const { shouldShowList, shouldShowEmptyState } = useVisibilityState(items);
+return (
+  <>
+    {shouldShowList && <ItemList items={items} />}
+    {shouldShowEmptyState && <EmptyState />}
+  </>
+);
+```
+
+#### Ternary Operators for Either/Or Cases
+
+```tsx
+{
+  items.length > 0 ? <ItemList items={items} /> : <EmptyState />;
+}
+```
+
+### Why This Approach?
+
+1. **Prevents Rendering Bugs**: No more accidentally rendering `0`, `""`, or `[object Object]`
+2. **Explicit Intent**: Code clearly shows what conditions trigger rendering
+3. **Consistent Architecture**: Same strict patterns across TypeScript and React code
+4. **Better Maintainability**: Conditions are clear and unambiguous
+5. **AI Code Safety**: Strict checks prevent subtle bugs in generated code
+
+## Example with Custom Rules
+
+```javascript
+// eslint.config.mjs
+import { createTypeAwareReactConfig } from "@reasonabletech/eslint-config/react";
+
+export default [
+  ...createTypeAwareReactConfig(import.meta.dirname),
+  {
+    // Component file patterns
+    files: ["**/components/**/*.{tsx,jsx}"],
+    rules: {
+      // Enforce component naming conventions
+      "react/function-component-definition": [
+        "error",
+        {
+          namedComponents: "function-declaration",
+          unnamedComponents: "arrow-function",
+        },
+      ],
+      // Stricter TypeScript rules for components
+      "@typescript-eslint/no-unused-vars": "error",
+    },
+  },
+  {
+    // Hook file patterns
+    files: ["**/hooks/**/*.{ts,tsx}"],
+    rules: {
+      // Stricter hook dependency checking
+      "react-hooks/exhaustive-deps": "error",
+      // Require JSDoc for custom hooks
+      "jsdoc/require-jsdoc": [
+        "error",
+        { require: { FunctionDeclaration: true } },
+      ],
+    },
+  },
+];
+```
+
+## Modular Architecture
+
+The React configuration is built from focused modules:
+
+### `src/react/plugins.ts`
+
+- React and React Hooks plugin configurations
+- Browser globals and environment setup
+- Plugin composition utilities
+
+### `src/react/rules.ts`
+
+- React-specific rules using shared React patterns
+- Integration with shared React rules from `src/shared/react-rules.ts`
+- Framework-specific rule extensions
+
+### `src/react/config.ts`
+
+- Complete configuration builder
+- Combines plugins, rules, and file-specific overrides
+- Orchestrates all React-specific configurations
+
+### Shared Components
+
+- `src/shared/react-rules.ts`: Common rules shared with Next.js config
+- `src/index.ts`: Base TypeScript configuration automatically included
+
+## Best Practices
+
+- Use the React configuration for any project that uses React
+- Consider using more specific configurations (Next.js) for framework-specific projects
+- Customize rules for specific file patterns to enforce different standards for components, hooks, etc.
+- Keep components and hooks in separate files to apply more targeted linting rules
+
+## Related Documentation
+
+- [Next.js Configuration](./next-config.md) — Next.js specific configuration
+- [API Reference](../api-reference.md) — Complete function documentation
+- [Usage Guide](../../guides/usage-guide.md) — Setup instructions and troubleshooting
+- [Refactoring React for Type Safety](../../tutorials/refactoring-react-for-type-safety.md) — Fixing strict-boolean-expressions in React components
+- [AI Code Safety](../../concepts/ai-code-safety.md) — Why strict linting matters