Skip to content
Coral Docs

Project Templates

Creating a New Coral Module

Section titled “Creating a New Coral Module”

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

Section titled “Recommended: use the CLI”

The fastest path is the official scaffolder:

Terminal window
pnpm create coral@latest
npm create coral@latest
bun create coral@latest

Or provide the module name up front:

Terminal window
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

Section titled “Template Repositories”

Coral Module Template

Section titled “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

Section titled “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

Section titled “Creating Your Module”

1. Scaffold from the Template

Section titled “1. Scaffold from the Template”

Recommended:

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

Manual fallback:

Terminal window
# 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

Section titled “2. Rename Your Module”

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

If you cloned manually, replace coral-module throughout:

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


# In .github/workflows/docker-publish.yml
IMAGE_NAME: my-module   # bare name. The workflow publishes two images:
                        #   ghcr.io/get-coral/<IMAGE_NAME>
                        #   <DOCKERHUB_USERNAME>/<IMAGE_NAME>


# In README.md
# My Module

3. Set Up Dependencies

Section titled “3. Set Up Dependencies”
Terminal window
pnpm install

4. Create Your App

Section titled “4. Create Your App”

The template is deliberately close to empty:

src/
├── routes/
│   ├── __root.tsx     # Root layout
│   └── index.tsx      # Home page
├── router.tsx         # Router setup
├── routeTree.gen.ts   # Generated — do not edit
├── styles.css
├── env.d.ts
└── example.test.tsx

There is no api/ or components/ directory yet; create them as you need them, following TanStack Start’s file-based routing conventions.

5. Configure Jellyfin Connection

Section titled “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

Section titled “6. Test Locally”
Terminal window
pnpm dev

Runs on http://localhost:3000

Module Structure

Section titled “Module Structure”

Key Directories

Section titled “Key Directories”
  • src/routes/ - Page components and API routes
  • public/ - Static assets
  • .github/workflows/ - CI/CD pipelines

Existing modules also use src/components/, src/lib/ and src/server/. Those are conventions worth following, not directories the template ships.

Configuration Files

Section titled “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

Section titled “Development Workflows”

Local Development

Section titled “Local Development”
Terminal window
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

Section titled “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

Section titled “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, 'Movie', {
  limit: 24,
  sortBy: 'SortName'
})

Styling with Tailwind

Section titled “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

Section titled “Docker Deployment”

The template includes a Dockerfile for containerization:

Terminal window
# 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

Section titled “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

Section titled “Publishing”

npm (for libraries)

Section titled “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

Section titled “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)

Section titled “Vercel (optional)”

For web applications:

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

Example Implementations

Section titled “Example Implementations”

Reference existing modules:

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

Maintenance

Section titled “Maintenance”

Keeping Up

Section titled “Keeping Up”
  • Update dependencies regularly: pnpm update
  • Monitor security advisories
  • Keep @get-coral/biome-config and @get-coral/tsconfig current — they carry the shared defaults

Upgrading TanStack Start

Section titled “Upgrading TanStack Start”
Terminal window
pnpm update @tanstack/react-start @tanstack/react-router

The package is @tanstack/react-start; @tanstack/start was its old name. Check release notes for breaking changes.

Getting Help

Section titled “Getting Help”

Next Steps

Section titled “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

Section titled “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! 🚀

Section titled “Related”