Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: new contribution guideline for client structure #2793

Merged
merged 3 commits into from
Jan 9, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 151 additions & 0 deletions apps/engineering/content/docs/contributing/client-structure.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
---
title: Client-Side Structure
description: How to structure your PR when contributing to Unkey dashboard
---

# 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
ogzhanolguncu marked this conversation as resolved.
Show resolved Hide resolved
│ ├── 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:

```typescript
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`)
ogzhanolguncu marked this conversation as resolved.
Show resolved Hide resolved
- 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:

```typescript
// /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!
2 changes: 1 addition & 1 deletion apps/engineering/content/docs/contributing/meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,5 @@
"description": "oss/acc",
"icon": "GitPullRequest",
"root": true,
"pages": ["index", "sdk-development", "testing", "versions"]
"pages": ["index", "sdk-development", "testing", "versions", "client-structure"]
}
Loading