Naming Conventions
Document: 09-naming-conventions.md
Version: 1.0.0
Purpose
This document defines the official naming conventions used across all Rundown projects.
Consistent naming improves readability, reduces ambiguity, simplifies onboarding, and ensures that every project follows the same organizational standards.
These conventions apply to all production projects unless an approved exception exists.
General Principles
Every name should be:
-
Descriptive
-
Consistent
-
Predictable
-
Easy to search
-
Easy to understand
Avoid abbreviations unless they are universally recognized.
Examples:
✅ product-card
❌ pc
Repositories
Convention
kebab-case
Examples:
midnight-and-marigold
les-baskets
magtik-bharat
exfinity-website
rundown-os
rundown-starter-kit
Rules:
-
Lowercase only
-
Hyphens between words
-
No spaces
-
No underscores
Directories
Convention
lowercase
Examples:
components
features
hooks
lib
payload
styles
utils
types
public
Rules:
-
Lowercase only
-
No spaces
-
No PascalCase
React Components
Convention
PascalCase
Examples:
Button.tsx
Navbar.tsx
Footer.tsx
HeroSection.tsx
ProductCard.tsx
PricingTable.tsx
Avoid:
button.tsx
hero.tsx
component.tsx
React Hooks
Convention
File: kebab-case
Exported Hook: camelCase beginning with use
Example:
use-theme.ts
use-scroll.ts
use-media-query.ts
export function useTheme() {}
Utility Functions
Convention
File: kebab-case
Exported Function: camelCase
Examples:
format-currency.ts
generate-metadata.ts
slugify.ts
capitalize.ts
export function formatCurrency() {}
TypeScript Types & Interfaces
File
kebab-case
Examples:
product.ts
navigation.ts
order.ts
user.ts
Interface
PascalCase
export interface Product {}
export interface User {}
Next.js Routes
Static Routes
Use lowercase with hyphens.
Examples:
/about
/contact
/our-services
/case-studies
Dynamic Routes
Examples:
/blog/[slug]
/products/[id]
/portfolio/[project]
Route names should be descriptive and SEO-friendly.
API Routes
Use lowercase with hyphens.
Examples:
/api/contact
/api/orders
/api/create-payment
/api/newsletter
Avoid camelCase in URLs.
Payload CMS
Collections
Plural
Lowercase
Examples:
products
posts
authors
categories
users
Globals
Singular
Lowercase
Examples:
navigation
footer
site-settings
seo
Blocks
Folder:
lowercase
Examples:
hero
gallery
faq
pricing
cta
React Component:
PascalCase
Examples:
HeroBlock.tsx
GalleryBlock.tsx
PricingBlock.tsx
Environment Variables
Convention:
UPPER_SNAKE_CASE
Examples:
DATABASE_URL
PAYLOAD_SECRET
NEXT_PUBLIC_SITE_URL
NEXT_PUBLIC_API_URL
R2_ACCESS_KEY
R2_SECRET_KEY
Rules:
-
Public variables must begin with
NEXT_PUBLIC_. -
Secrets must never use the public prefix.
CSS
CSS Variables
Convention:
kebab-case
Examples:
--color-primary
--color-secondary
--spacing-lg
--radius-md
Tailwind
Prefer Tailwind utility classes over custom CSS whenever practical.
Custom CSS should be reserved for:
-
Design tokens
-
Complex animations
-
Third-party overrides
Assets
Use descriptive filenames.
Examples:
hero-home.webp
team-john-smith.webp
product-running-shoe.webp
portfolio-modern-office.webp
Avoid:
IMG001.jpg
final.png
image-new.webp
Docker
Images
kebab-case
Example:
rundown-starter-kit
Containers
Convention:
client-name-app
client-name-db
client-name-redis
Example:
magtik-app
magtik-db
magtik-redis
Git Branches
Convention:
feature/navbar
feature/product-search
fix/mobile-menu
hotfix/payment-error
docs/update-handbook
chore/update-dependencies
Branch names should clearly describe the work being performed.
Database
Tables
Plural
snake_case
Examples:
users
products
order_items
blog_posts
Columns
snake_case
Examples:
created_at
updated_at
product_name
user_id
Best Practices
-
Prefer complete words over abbreviations.
-
Keep names concise without sacrificing clarity.
-
Follow framework conventions unless Rundown defines a different standard.
-
Avoid inconsistent capitalization.
-
Use the same terminology throughout the project.
Engineering Decision
Naming Philosophy
Status: Accepted
Decision
Rundown adopts established industry conventions wherever practical rather than inventing custom naming rules.
Reasoning
Using widely accepted conventions:
-
Reduces onboarding time.
-
Improves compatibility with frameworks.
-
Produces more predictable code.
-
Aligns with AI-assisted development tools.
Custom conventions should only be introduced when they provide a measurable benefit.
Naming Checklist
Before creating a new file, directory, or identifier, verify:
-
Does it follow the correct naming convention?
-
Is the name descriptive?
-
Does it match existing terminology?
-
Is the capitalization correct?
-
Will another developer understand it immediately?
Summary
Consistent naming conventions improve readability, maintainability, and collaboration across all Rundown projects.
Following these standards ensures every project shares a common vocabulary, making the codebase easier to navigate and reducing unnecessary cognitive overhead.
Related Documents
Related ADRs
-
ADR-001: Repository Structure
-
ADR-002: Git Workflow