Project Templates

Creating a New Coral Module

Coral provides templates to help you build new modules. All Coral modules follow the same architecture and conventions.

Recommended: use the CLI

The fastest path is the official scaffolder:

pnpm create coral@latest
npm create coral@latest
bun create coral@latest

Or provide the module name up front:

pnpm create coral@latest my-module

The CLI pulls the latest template/, renames the module, and keeps the standard Coral TypeScript, Biome, and release automation setup intact. See create-coral CLI for the dedicated command reference.

Template Repositories

Coral Module Template

The standard template for building a new Coral module with TanStack Start, React, Tailwind CSS, and Jellyfin integration.

Get started with the template

What’s Included

• TanStack Start - React SSR framework
• File-based routing - Simple route organization
• Tailwind CSS v4 - Styling
• TypeScript - Full type safety
• Jellyfin API integration - Ready to connect
• Docker - Container deployment
• GitHub Actions - CI/CD workflows
• Biome - Linting and formatting
• pnpm - Package management

Creating Your Module

1. Scaffold from the Template

Recommended:

pnpm create coral@latest my-module
cd my-module

Manual fallback:

# Click "Use this template" on GitHub
# Or clone and customize
git clone https://github.com/Get-Coral/template.git my-module
cd my-module

2. Rename Your Module

If you used the CLI, this step is already handled for you.

If you cloned manually, replace coral-module throughout:

# In package.json
{
  "name": "@get-coral/my-module"
}

# In .github/workflows/docker-publish.yml
IMAGE_NAME=ghcr.io/Get-Coral/my-module

# In README.md
# My Module

3. Set Up Dependencies

pnpm install

4. Create Your App

The template includes:

src/routes/
├── index.tsx          # Home page
├── api/
│   └── example.ts     # API endpoint
└── components/        # Reusable components

Add your pages and components following TanStack Start conventions.

5. Configure Jellyfin Connection

.env

JELLYFIN_URL=http://your-server:8096
JELLYFIN_API_KEY=your-api-key
JELLYFIN_USER_ID=your-user-id

Or use local SQLite setup like other modules.

6. Test Locally

pnpm dev

Runs on http://localhost:3000

Module Structure

Key Directories

• src/routes/ - Page components and API routes
• src/components/ - Reusable UI components
• src/lib/ - Utilities and helpers
• src/integrations/ - External service integration
• public/ - Static assets
• .github/workflows/ - CI/CD pipelines

Configuration Files

• package.json - Dependencies
• tsconfig.json - TypeScript config
• biome.json - Linting rules
• vite.config.ts - Build config
• Dockerfile - Container image
• .env.example - Environment template

Development Workflows

Local Development

pnpm dev          # Start dev server
pnpm build        # Build for production
pnpm preview      # Preview production build
pnpm lint         # Run linter
pnpm format       # Format code
pnpm typecheck    # Check types

Using TanStack Start

TanStack Start provides:

• File-based routing - Files in src/routes/ become routes
• API routes - Create src/routes/api/ endpoints
• Server functions - Call server code from client
• React Server Components - Components that run on server

Building with Jellyfin

Import the client:

import { createClient, getLibraryItems } from '@get-coral/jellyfin'

const client = createClient({
  url: process.env.JELLYFIN_URL,
  apiKey: process.env.JELLYFIN_API_KEY,
  userId: process.env.JELLYFIN_USER_ID
})

const items = await getLibraryItems(client, {
  parentId: 'library-id'
})

Styling with Tailwind

The template includes Tailwind CSS v4 with:

• Modern utility classes
• Dark mode support
• Responsive design
• Custom configuration

Edit src/styles.css to customize colors and theme.

Docker Deployment

The template includes a Dockerfile for containerization:

# Build image
docker build -t my-module .

# Run container
docker run -p 3000:3000 \
  -e JELLYFIN_URL=http://jellyfin:8096 \
  -e JELLYFIN_API_KEY=key \
  -e JELLYFIN_USER_ID=id \
  my-module

GitHub Actions

The template includes workflows for:

• Docker publish - Build and push to container registry
• Release - Automated release management (with release-please)
• Tests - Run tests on PR

Update .github/workflows/ for your module.

Publishing

npm (for libraries)

If creating a library like the Jellyfin client:

1. Update package.json with public scope
2. Configure npm publishing in workflows
3. Create releases on GitHub
4. Package is published to npm

Docker Registry

For applications and modules:

1. Configure container registry credentials
2. Docker image is built and pushed on release
3. Pull with docker pull image-name:version

Vercel (optional)

For web applications:

1. Connect GitHub repo to Vercel
2. Set environment variables
3. Automatic deployments on push

Example Implementations

Reference existing modules:

• Aurora - Full video client
• Fathom - Reading interface
• KAPOW - Complex real-time app

Maintenance

Keeping Up

• Update dependencies regularly: pnpm update
• Monitor security advisories
• Update Tailwind CSS v4
• Update TanStack packages

Upgrading TanStack Start

pnpm add -u @tanstack/start
pnpm add -u @tanstack/router

Check release notes for breaking changes.

Getting Help

• Refer to TanStack Start docs
• Check Tailwind CSS v4 docs
• Open a GitHub Discussion
• Join Jellyfin community

Next Steps

1. Run pnpm create coral@latest
2. Rename your module
3. Build your feature
4. Deploy and share
5. Open a PR to list in Coral ecosystem

Submit to Coral

When ready to share:

1. Push to GitHub
2. Create releases with version tags
3. Submit to ecosystem for listing

---

Happy building! 🚀