Documentation/Creating Realms/Structure

Realm Structure

Understanding the anatomy of a RealmKit template. Learn how to organize your project files, configure metadata, and create AI-ready documentation.

What is a Realm?

A realm is a complete project template with AI-optimized documentation

Complete Project

Full application with all necessary files, dependencies, and configurations

AI-Ready Docs

Structured documentation that AI assistants can understand and use effectively

Configurable

Features can be enabled/disabled based on project requirements

File Structure

Standard organization for RealmKit templates

.realmkit/
required
RealmKit metadata and configuration
realm.yml
required
Realm configuration and metadata
ai-context/AI assistant documentation
00-CORE.mdCore project overview
01-AUTH.mdAuthentication system
02-FEATURES.mdFeature documentation
README.mdAI context index
ai-context/Alternative AI context location
src/ or app/
required
Main application source code
package.json
required
Node.js dependencies and scripts
README.md
required
Project documentation
.gitignoreGit ignore patterns
Structure Guidelines
  • • The .realmkit/ directory contains metadata and AI context
  • • AI context can also be in the root ai-context/ directory
  • • Follow the target framework's conventions for source code organization
  • • Include examples and documentation for all features

realm.yml Configuration

The main configuration file that defines your realm's metadata and features

Example Configuration

# .realmkit/realm.yml
name: "saas-starter"

version: "1.0.0"

description: "Complete SaaS application starter with authentication and payments"

category: "saas"

tags:
  0: "nextjs"
  1: "typescript"
  2: "prisma"
  3: "stripe"
  4: "auth"

author:
  name: "RealmKit Team"
  email: "team@realmkit.com"
  url: "https://realmkit.com"

repository: "https://github.com/realmkit/saas-starter"

license: "MIT"

features:
  auth:
    enabled: true
    providers: ["email","google","github"]
    description: "Multi-provider authentication system"
  payments:
    enabled: true
    provider: "stripe"
    description: "Subscription and one-time payments"
  database:
    enabled: true
    provider: "postgresql"
    orm: "prisma"
    description: "PostgreSQL with Prisma ORM"

scripts:
  setup: "npm install && npm run db:setup"
  dev: "npm run dev"
  build: "npm run build"

requirements:
  node: ">=18.0.0"
  npm: ">=8.0.0"

Required Fields

  • name - Unique identifier
  • version - Semantic version
  • description - Clear summary
  • category - Primary category

Optional Fields

  • tags - Searchable keywords
  • features - Feature flags
  • scripts - Setup commands
  • requirements - Dependencies

Best Practices

Use Descriptive Names

Choose clear, descriptive names that indicate the realm's purpose

✓ Good Examples

  • • saas-starter
  • • nextjs-blog
  • • api-template

✗ Avoid

  • • my-app
  • • project1
  • • template

Include Complete Setup

Provide all necessary files for a working project

✓ Good Examples

  • • package.json
  • • config files
  • • environment examples

✗ Avoid

  • • missing dependencies
  • • broken configs
  • • incomplete setup

Document Everything

Include comprehensive README and AI context files

✓ Good Examples

  • • clear setup instructions
  • • feature documentation
  • • API references

✗ Avoid

  • • minimal docs
  • • outdated info
  • • missing context

Follow Conventions

Use standard project structure and naming conventions

✓ Good Examples

  • • src/ for source
  • • docs/ for documentation
  • • tests/ for testing

✗ Avoid

  • • non-standard layouts
  • • confusing organization
  • • mixed conventions

Feature Configuration

How to define configurable features in your realm

Feature Definition

features:
  auth:
    enabled: true
    providers: ["email", "google", "github"]
    description: "Multi-provider authentication"
    files:
      - "src/lib/auth.ts"
      - "src/pages/api/auth/[...nextauth].ts"
    
  payments:
    enabled: false  # Optional feature
    provider: "stripe"
    description: "Payment processing with Stripe"
    dependencies:
      - "stripe"
      - "@stripe/stripe-js"

Feature Properties

  • enabled - Whether feature is active by default
  • description - Clear explanation of what it does
  • files - List of related files
  • dependencies - Required packages
  • config - Configuration options

Common Features

  • • Authentication systems
  • • Payment processing
  • • Database integrations
  • • Admin panels
  • • Email services
  • • File uploads

Next Steps

Continue learning about realm development

AI Context Files
Make realms AI-assistant ready
Publishing Guide
Share your realm with others
CLI Reference
Command line tools