Client-Side Structure Contribution Guidelines

Overview

When contributing to the Unkey dashboard or any client app in the Unkey repository, we follow a feature-based architecture. This guide will help you understand how to structure your code to maintain consistency across the project.

Directory Structure

Each feature (typically corresponding to a Next.js page) should be organized as a self-contained module with the following structure:

feature-name/
├── components/              # Feature-specific React components
│   ├── component-name/      # Complex components get their own directory
│   │   ├── index.tsx
│   │   └── sub-component.tsx
│   └── simple-component.tsx
├── hooks/                   # Custom hooks for the feature
│   ├── queries/             # API query hooks
│   │   ├── use-feature-list.ts
│   │   └── use-feature-details.ts
│   └── use-feature-logic.ts
├── actions/                 # Server actions and API calls
│   └── feature-actions.ts
├── types/                   # TypeScript types and interfaces
│   └── feature.ts
├── schemas/                 # Validation schemas
│   └── feature.ts
├── utils/                   # Helper functions
│   └── feature-helpers.ts
├── constants.ts             # Feature-specific constants
└── page.tsx                 # Main page component

Key Principles

1. Feature Isolation

   • Keep all related code within the feature directory
   • Don't import feature-specific components into other features
   • Use shared components from the global /components directory or unkey/ui package for common UI elements

2. Component Organization

   • Simple components can be single files (No need to break everything into 50 different files, follow your common sense)
   • Complex components should have their own directory with an index.tsx
   • Keep component-specific styles, tests, and utilities close to the component

3. Code Colocation

   • Place related code as close as possible to where it's used
   • If a utility is only used by one component, keep it in the component's directory

Example Page Structure

Here's an example of how to structure a typical page component:

import { Navbar } from "@/components/navbar"; // Global shared component
import { PageContent } from "@/components/page-content";
import { FeatureComponent } from "./components/feature-component";
 
export default function FeaturePage() {
  // Page implementation
  // This is also we where we do our server side data fetching.
  return (
    <div>
      <Navbar>{/* Navigation content */}</Navbar>
      <PageContent>
        {/* Entry to our actual component. This one is usually a client-side component */}
        <FeatureComponent />
      </PageContent>
    </div>
  );
}

Best Practices

1. File Naming

   • Use kebab-case for directory and file names
   • The directory structure itself provides context, so explicit suffixes are optional
   • If you choose to use suffixes for additional clarity, common patterns include:
     • auth.schema.ts or just auth-schema.ts for validation schemas
     • auth.type.ts or just auth-types.ts for type definitions
     • .client.tsx for client-specific components
     • .server.ts for server-only code
     • .action.ts for server actions

2. Code Organization

   • Keep files focused and single-purpose
   • Use index.ts files to expose public API of complex components
   • Colocate tests with the code they test
   • Place shared types in the feature's types directory

3. Imports and Exports

   • Use absolute imports for shared components (@/components)
   • Never use default exports unless it's absolutely necessary
   • Use relative imports within a feature
   • Export complex components through index files
   • Avoid circular dependencies

Shared Code

Global shared code should be placed in root-level directories:

/components          # Shared React components
/hooks               # Shared custom hooks
/utils               # Shared utilities
/types               # Shared TypeScript types
/constants           # Global constants

Only place code in these directories if it's used across multiple features.

Example Feature Implementation

Here's a practical example of how to structure a feature:

// /feature/components/feature-list/index.tsx
export function FeatureList() {
  // Component implementation
}
 
// /feature/hooks/queries/use-features.ts
export function useFeatures() {
  // Hook implementation
}
 
// /feature/actions/feature-actions.ts
export async function createFeature() {
  // Server action implementation
}
 
// /feature/types/feature.ts
export interface Feature {
  // Type definitions
}

Questions?

If you're unsure about where to place certain code or how to structure your feature, please don't hesitate to ask in our Discord community or in your pull request. We're here to help!