Stage 1: Project Setup and Configuration

1. Overview

• Objective: Establish the monorepo structure (@react-api-kit/core package), configure base tooling (TypeScript, ESLint, Prettier, ViTest, Rollup), and set up CI/CD tooling.
• Expected Result:
  • Functioning monorepo (/packages/core) with shared root configuration files (e.g., root tsconfig.json, ESLint, Prettier)
  • Configured CI pipeline (GitHub Actions)
  • Build process that compiles the initial core package structure without errors.

2. Dependency Validation

• Pre-Stage Requirements: Initial development environment setup (Node.js, NPM with Workspaces).
• External Dependencies: Lerna, TypeScript, ESLint, Prettier, ViTest, Rollup (with plugins: typescript, node-resolve, commonjs), rimraf (for clean script). Add axios and zustand as core dependencies.
• External Dependencies: typescript, eslint, prettier, vitest, rollup (with plugins: typescript, node-resolve, commonjs), axios, zustand, relevant @types/*.
• Environment Configurations: Basic CI environment variables (if any).

3. Diagrams

• Visual Aids:

  graph LR
      A[Root Directory] --> B[packages/core]
  
      subgraph "Monorepo Root"
          direction LR
          R_PKG["package.json"]
          R_TS["tsconfig.json"]
          R_ES["eslintrc.js"]
          R_PR["prettierrc"]
          R_VITEST["vitest.config.js"]
          R_GIT["github/workflows/ci.yml"]
      end
  
      subgraph "@react-api-kit/core Package"
          direction LR
          C_PKG["package.json"]
          C_TS["tsconfig.json"]
          C_ROLL["rollup.config.js"]
          C_SRC["src/index.ts"]
      end
  
      A --- R_PKG & R_TS & R_ES & R_PR & R_VITEST & R_GIT
      A --- B --- C_PKG & C_TS & C_ROLL & C_SRC
  
      C_TS -- extends --> R_TS
      C_PKG -- uses deps from --> R_PKG
  

  Loading

4. Touched Parts

• Modules/Files:

  • Root Files:
    • package.json: Configure workspaces (packages/core), add root dev dependencies (typescript, vitest, eslint, prettier, rollup, @rollup/plugin-*, rimraf, @types/*). Define root scripts (bootstrap, build, test, lint).
    • tsconfig.json: Define base TS compiler options (target ES2018+, module ESNext, strict, declaration, sourceMap, esModuleInterop, skipLibCheck, isolatedModules). Configure composite project references.
    • .eslintrc.js: Configure ESLint parser (@typescript-eslint/parser), plugins (@typescript-eslint, react, react-hooks, prettier), extends (eslint:recommended, plugin:react/recommended, plugin:@typescript-eslint/recommended, plugin:prettier/recommended), rules (react/react-in-jsx-scope: off, etc.). Define settings (react version).
    • .prettierrc.js or .prettierrc.json: Define formatting rules (semi: true, singleQuote: true, tabWidth: 2, trailingComma: 'es5', printWidth: 80).
    • vitest.config.js: Configure base ViTest settings.
    • .github/workflows/ci.yml: Setup basic workflow (triggers on push/PR, matrix for Node versions, steps: checkout, setup node, install deps, lint, test, build).
  • /packages/core Package:
    • /packages/core/package.json: Create package definition (name: "@react-api-kit/core", version, description, main, module, types, files: ["dist"]). Add dependencies: axios, zustand. Add peerDependencies: react. Add optional RN peer dependencies (@react-native-community/netinfo, react-native-encrypted-storage, react-native-linking, react-native-app-auth) using peerDependenciesMeta. Define package scripts (build, dev, test, lint, clean). Add repository, keywords, author, license.
    • /packages/core/tsconfig.json: Create package-specific TS config (extends, compilerOptions.outDir, compilerOptions.rootDir, include: ["src/**/*"], exclude: ["node_modules", "dist", "**/__tests__"]).
    • /packages/core/rollup.config.js: Setup Rollup (input src/index.ts, output CJS/ESM formats in dist/, sourcemaps, plugins: typescript, node-resolve, commonjs). Mark peer dependencies as external.
    • /packages/core/src/index.ts: Create initial empty entry point file.

• Functionalities:

  • Establish monorepo workspace structure.
  • Define base code quality, formatting, and compilation settings.
  • Set up automated CI checks.
  • Create the skeleton for the core package with build/test configurations and essential dependencies.

5. API Contracts & Interface Definitions

• Configuration Contracts (Implicit via Files):
  • Root config files define baseline standards for TypeScript, ESLint, Prettier, ViTest.
• Package Interface Contracts (/packages/core/package.json):
  • Specifies the package name, version, entry points (main, module, types), included files (files), core dependencies (axios, zustand), peer dependencies (react), optional RN peer dependencies, and standard build/test/lint scripts.
• Public API Entry Point (/packages/core/src/index.ts):
  • Initially empty or contains placeholder exports. Defines the starting point for the package's public API surface.

6. Tests

• Frameworks & Coverage Goals: Configure ViTest. Set coverage reporting (e.g., Clover, JSON) and target >90% for later stages.
• Initial Tests: Add a placeholder test file (src/tests/index.test.ts) ensuring the test runner executes correctly within the core package environment.

7. Integration Checkpoints

• Monorepo structure correctly set up; package installation works via workspace commands.
• Shared configuration files are correctly inherited/applied to the core package.
• Build script (npm run build --workspace=@react-api-kit/core) successfully generates dist folder with CJS/ESM files for core package (@react-api-kit/core) using Rollup.
• Test script (npm run test) runs successfully using root ViTest config.
• Lint script (npm run lint --workspace=@react-api-kit/core) runs successfully using root ESLint config.
• CI pipeline executes build, lint, and test steps successfully.

8. Documentation Deliverables

• Root README.md: Explain monorepo structure, refined project purpose, development workflow (install, build, test, lint commands).
• /packages/core/README.md: Briefly explain the purpose of the core package.
• CONTRIBUTING.md: Outline contribution process, code style, PR requirements.
• Initialize CHANGELOG.md: Start tracking changes; define SemVer policy.

9. Considerations & Notes

• Ensure TypeScript strict mode is enabled in the base tsconfig.json.
• Configure Rollup to correctly handle external peer dependencies and generate accurate type definition files (.d.ts).

10. Platform-Specific Implementations

• Base TSConfig (lib, jsx) should support both Web and React Native targets.
• ESLint config includes rules relevant for React/hooks applicable to both.
• Rollup output should be compatible with both web bundlers (Webpack, Vite) and React Native's Metro bundler.