Package Conventions

These conventions apply to all reusable Kateb Tech packages.

Package Structure

Each package should expose a clear public API and keep implementation details internal.

Prefer feature-based folders such as:

src
├── form
├── routes
├── utils
└── index.ts

Import Rules

Inside a package, prefer relative imports.

import { FieldError } from "./FieldError";

Avoid importing the package from itself:

import { FieldError } from "@katebtech/core/form/controls";

Public Exports

Export public components, helpers, and useful public types.

export { Input } from "./Input";
export type { InputProps } from "./types";

Keep internal implementation type private.

Subpath imports

Prefer specific pacakge subpaths when consuming package APIs.

import { cn } from "@katebtech/core/utils";
import { Header } from "@katebtech/core/typography";

Naming

Use consistent naming across packages.

• PascalCase for React components
• camelCase for functions and variables
• UPPER_SNAKE_CASE for shared constants
• desriptive file an folder name

TypeScript

Avoid any unless there is a strong reason

Prefer:

• explicit public types
• readonly for immutable data
• discriminated unions for state/result shapes
• as const where literal types are useful

Package Dependencies

Lower-level packages should not depend on higher-level package.

exmaple:

@katebtech/core
    ↓
@katebtech/layout
    ↓
@katebtech/pages

Avoid circular Dependencies.

README Structure

Each package README should follow the same basic structure:

Package name
Short description

Purpose
Package Overview
File Structure
Import Style
Package Rules
Module Documentation

Documentation Rule

Package READMEs should document:

• what the package provides
• how to import it
• how to use its public APIs
• package-specific-architecture
• package-specific-constraints

Do not duplicate general Git, pnpm, publishing, or repository commands inside Package READMEs.

Those belong in the central Command documentations.

Release Rule

Before publishing a package:

pnpm check

Then update the package version appropriately and publish through Github Packages.

See the central package publishing documentation for the full release workflow.