Stacks CMS
Key Paths
- Core package:
storage/framework/core/cms/src/
- Models:
storage/framework/defaults/app/Models/Content/ (Post, Author, Page)
- Models:
storage/framework/defaults/app/Models/ (Comment, Tag)
- Actions:
storage/framework/defaults/app/Actions/Cms/
- Routes:
routes/api.ts (CMS and blog endpoints)
- Config:
config/blog.ts
Source Files
cms/src/
├── index.ts # CmsNamespace — top-level API
├── posts/
│ ├── fetch.ts # fetchById, fetchAll, fetchByStatus, fetchByCategory, fetchByAuthor
│ ├── store.ts # store, attach, detach, sync (pivot tables)
│ ├── update.ts # update
│ └── destroy.ts # destroy, bulkDestroy
├── authors/
│ ├── fetch.ts # fetchAll, fetchById, findByEmail, findByName, findByUserId
│ ├── store.ts # store, findOrCreate
│ ├── update.ts # update
│ └── destroy.ts # destroy
├── pages/
│ ├── fetch.ts # fetchById, fetchAll, fetchByTemplate, fetchByAuthor
│ └── store.ts # store
├── categorizables/ # Categories with polymorphic pivot
├── taggables/ # Tags with polymorphic pivot
├── commentables/ # Comments with polymorphic support
└── build.ts # Blog static site generation
CMS Namespace
interface CmsNamespace {
posts: PostsModule
postCategories: PostCategoriesModule
tags: TagsModule
comments: CommentsModule
authors: AuthorsModule
pages: PagesModule
}
Models
Post
- Table:
posts
- Relationships:
belongsTo(['Author'])
- Traits: UUID, Timestamps, Search, Seeder (20), Categorizable, Taggable, Commentable, API routes
| Field |
Type |
Validation |
Default |
| title |
string |
required, 3-255 chars |
— |
| content |
string |
required, 10-1000 chars |
— |
| excerpt |
string |
optional, 10-500 chars |
— |
| poster |
string |
optional, valid URL |
— |
| views |
number |
— |
0 |
| publishedAt |
timestamp |
optional |
— |
| status |
enum |
published/draft/archived |
draft |
| isFeatured |
number |
0 or 1 |
— |
Author
- Table:
authors, Relationships: hasMany(['Post']), belongsTo(['User'])
- Attributes:
name (5-255), email (unique, valid email)
- Indexes: Composite on
(email, name)
Page
- Table:
pages, Relationships: belongsTo(['Author'])
- Attributes:
title, template (enum: default/landing/blog/contact), views, conversions, publishedAt
Comment
- Table:
comments, Relationships: belongsTo(['Post', 'User'])
- Attributes:
authorName, authorEmail, content (1-2000), status (pending/approved/spam/trash), ipAddress, userAgent, isApproved
Tag
- Table:
tags
- Attributes:
name (unique, 2-50), slug (unique), description, postCount, color
Posts API
// Fetch
cms.posts.fetchById(id: number): Promise<PostJsonResponse | undefined>
cms.posts.fetchAll(): Promise<PostJsonResponse[]>
cms.posts.fetchByStatus(status: 'published' | 'draft' | 'archived'): Promise<PostJsonResponse[]>
cms.posts.fetchByCategory(category: string): Promise<PostJsonResponse[]>
cms.posts.fetchByAuthor(author: string): Promise<PostJsonResponse[]>
cms.posts.fetchByMinViews(minViews: number): Promise<PostJsonResponse[]>
cms.posts.fetchPublishedAfter(timestamp: number): Promise<PostJsonResponse[]>
// Store with pivot auto-attach
cms.posts.store(data: NewPost & { body?: string, category?: string }): Promise<PostJsonResponse>
cms.posts.attach(postId, tableName: 'categorizable_models' | 'taggable_models', ids: number[]): Promise<void>
cms.posts.detach(postId, tableName, ids?: number[]): Promise<void>
cms.posts.sync(postId, tableName, ids: number[]): Promise<void>
// Update & Destroy
cms.posts.update(id: number, data: Partial<PostUpdate>): Promise<PostJsonResponse>
cms.posts.destroy(id: number): Promise<boolean>
cms.posts.bulkDestroy(ids: number[]): Promise<number>
Authors API
cms.authors.findOrCreate(data: AuthorData): Promise<AuthorJsonResponse>
cms.authors.store(data: NewAuthor): Promise<AuthorJsonResponse>
cms.authors.findByEmail(email: string): Promise<AuthorJsonResponse | undefined>
cms.authors.findByName(name: string): Promise<AuthorJsonResponse | undefined>
cms.authors.findByUserId(userId: number): Promise<AuthorJsonResponse | undefined>
cms.authors.fetchAll(): Promise<AuthorJsonResponse[]>
cms.authors.fetchById(id: number): Promise<AuthorJsonResponse | undefined>
cms.authors.update(id, data): Promise<AuthorJsonResponse>
cms.authors.destroy(id): Promise<boolean>
Tags API
cms.tags.findOrCreateMany(names: string[], taggableType: string): Promise<number[]>
cms.tags.firstOrCreate(name: string, taggableType: string): Promise<TaggableTable>
cms.tags.fetchTags(): Promise<TaggableTable[]>
cms.tags.fetchTagById(id: number): Promise<TaggableTable | undefined>
cms.tags.countTaggedPosts(taggableType: string): Promise<number>
cms.tags.findMostUsedTag(taggableType?: string): Promise<{ name: string, count: number } | null>
cms.tags.fetchTagsWithPostCounts(): Promise<Array<{ name: string, postCount: number }>>
cms.tags.fetchTagDistribution(): Promise<Array<{ name: string, count: number, percentage: number }>>
Comments API
cms.comments.createComment(data: CreateCommentInput): Promise<CommentablesTable>
cms.comments.updateComment(id: number, input: UpdateCommentInput): Promise<CommentablesTable>
cms.comments.approveComment(id: number): Promise<CommentablesTable>
cms.comments.rejectComment(id: number): Promise<CommentablesTable>
cms.comments.deleteComment(id: number): Promise<void>
Routes
CMS Admin Routes
| Method |
Path |
Action |
| GET |
/cms/posts |
PostIndexAction |
| GET |
/cms/posts/{id} |
PostShowAction |
| POST |
/cms/posts |
PostStoreAction |
| PATCH |
/cms/posts/{id} |
PostUpdateAction |
| DELETE |
/cms/posts/{id} |
PostDestroyAction |
| PATCH |
/cms/posts/{id}/views |
PostViewsUpdateAction |
| CRUD |
/cms/authors/* |
Author CRUD |
| CRUD |
/cms/categories/* |
Categorizable CRUD |
| CRUD |
/cms/tags/* |
Taggable CRUD |
| CRUD |
/cms/comments/* |
Comment CRUD |
| CRUD |
/cms/pages/* |
Page CRUD |
Public Blog Routes
| Method |
Path |
Description |
| GET |
/blog/posts |
Public post listing |
| GET |
/blog/posts/{id} |
Public post detail |
| GET |
/blog/categories |
Public categories |
| GET |
/blog/tags |
Public tags |
| GET |
/blog/feed.xml |
RSS 2.0 feed (20 recent) |
| GET |
/blog/sitemap.xml |
XML sitemap for SEO |
Blog Configuration (config/blog.ts)
{
subdomain: 'blog',
title: 'Stacks Blog',
description: 'The official Stacks.js blog',
postsPerPage: 10,
enableComments: true, // declared, NOT yet honoured by the static builder
enableRss: true, // generates feed.xml
enableSitemap: true, // generates sitemap.xml
enableSearch: true, // declared, NOT yet honoured by the static builder
social: { twitter: '@stacksjs', github: 'stacksjs/stacks' },
theme: { primaryColor: '#3451b2', logo: '/images/logos/logo-transparent.svg' },
}
Database Tables
| Table |
Purpose |
posts |
Blog posts |
authors |
Content creators |
pages |
Static pages |
comments |
Comments (polymorphic) |
tags |
Tag definitions |
taggable_models |
Polymorphic pivot: tag ↔ model |
categorizables |
Category definitions |
categorizable_models |
Polymorphic pivot: category ↔ model |
Gotchas
- Polymorphic relations — categories, tags, and comments use
*_type fields to support multiple model types
- Post
content maps from body — the model attribute is content but the DB column mapping comes from body
- Author uses findOrCreate —
PostStoreAction auto-creates authors if they don't exist
- Post store auto-attaches — creating a post with category/tag data automatically calls
attach() on pivot tables
- Post update uses sync — updating categories/tags uses
sync() (detaches removed, attaches new)
- Views increment is atomic —
PATCH /cms/posts/{id}/views increments by 1
- RSS returns 20 items — hardcoded to 20 most recent published posts
- Sitemap priorities — posts 0.8, categories 0.6, blog homepage 0.9
- Comment status flow — starts
pending, can be approved, rejected (→ spam), or trashed
1---2name: stacks-cms-43description: Use when working with the CMS in a Stacks application - posts, authors, pages, categories, tags, comments, blog configuration, RSS feeds, or sitemaps. Covers @stacksjs/cms, CMS models, routes, and actions.4license: MIT5compatibility: Bun >= 1.3.0, TypeScript6allowed-tools: Read Edit Write Bash Grep Glob7metadata:8 source: https://skillmd.com/skills/stacksjs/stacks-cms-49---1011# Stacks CMS1213## Key Paths14- Core package: `storage/framework/core/cms/src/`15- Models: `storage/framework/defaults/app/Models/Content/` (Post, Author, Page)16- Models: `storage/framework/defaults/app/Models/` (Comment, Tag)17- Actions: `storage/framework/defaults/app/Actions/Cms/`18- Routes: `routes/api.ts` (CMS and blog endpoints)19- Config: `config/blog.ts`2021## Source Files22```23cms/src/24├── index.ts # CmsNamespace — top-level API25├── posts/26│ ├── fetch.ts # fetchById, fetchAll, fetchByStatus, fetchByCategory, fetchByAuthor27│ ├── store.ts # store, attach, detach, sync (pivot tables)28│ ├── update.ts # update29│ └── destroy.ts # destroy, bulkDestroy30├── authors/31│ ├── fetch.ts # fetchAll, fetchById, findByEmail, findByName, findByUserId32│ ├── store.ts # store, findOrCreate33│ ├── update.ts # update34│ └── destroy.ts # destroy35├── pages/36│ ├── fetch.ts # fetchById, fetchAll, fetchByTemplate, fetchByAuthor37│ └── store.ts # store38├── categorizables/ # Categories with polymorphic pivot39├── taggables/ # Tags with polymorphic pivot40├── commentables/ # Comments with polymorphic support41└── build.ts # Blog static site generation42```4344## CMS Namespace4546```typescript47interface CmsNamespace {48 posts: PostsModule49 postCategories: PostCategoriesModule50 tags: TagsModule51 comments: CommentsModule52 authors: AuthorsModule53 pages: PagesModule54}55```5657## Models5859### Post60- **Table**: `posts`61- **Relationships**: `belongsTo(['Author'])`62- **Traits**: UUID, Timestamps, Search, Seeder (20), Categorizable, Taggable, Commentable, API routes6364| Field | Type | Validation | Default |65|-------|------|------------|---------|66| title | string | required, 3-255 chars | — |67| content | string | required, 10-1000 chars | — |68| excerpt | string | optional, 10-500 chars | — |69| poster | string | optional, valid URL | — |70| views | number | — | 0 |71| publishedAt | timestamp | optional | — |72| status | enum | published/draft/archived | draft |73| isFeatured | number | 0 or 1 | — |7475### Author76- **Table**: `authors`, **Relationships**: `hasMany(['Post'])`, `belongsTo(['User'])`77- **Attributes**: `name` (5-255), `email` (unique, valid email)78- **Indexes**: Composite on `(email, name)`7980### Page81- **Table**: `pages`, **Relationships**: `belongsTo(['Author'])`82- **Attributes**: `title`, `template` (enum: default/landing/blog/contact), `views`, `conversions`, `publishedAt`8384### Comment85- **Table**: `comments`, **Relationships**: `belongsTo(['Post', 'User'])`86- **Attributes**: `authorName`, `authorEmail`, `content` (1-2000), `status` (pending/approved/spam/trash), `ipAddress`, `userAgent`, `isApproved`8788### Tag89- **Table**: `tags`90- **Attributes**: `name` (unique, 2-50), `slug` (unique), `description`, `postCount`, `color`9192## Posts API9394```typescript95// Fetch96cms.posts.fetchById(id: number): Promise<PostJsonResponse | undefined>97cms.posts.fetchAll(): Promise<PostJsonResponse[]>98cms.posts.fetchByStatus(status: 'published' | 'draft' | 'archived'): Promise<PostJsonResponse[]>99cms.posts.fetchByCategory(category: string): Promise<PostJsonResponse[]>100cms.posts.fetchByAuthor(author: string): Promise<PostJsonResponse[]>101cms.posts.fetchByMinViews(minViews: number): Promise<PostJsonResponse[]>102cms.posts.fetchPublishedAfter(timestamp: number): Promise<PostJsonResponse[]>103104// Store with pivot auto-attach105cms.posts.store(data: NewPost & { body?: string, category?: string }): Promise<PostJsonResponse>106cms.posts.attach(postId, tableName: 'categorizable_models' | 'taggable_models', ids: number[]): Promise<void>107cms.posts.detach(postId, tableName, ids?: number[]): Promise<void>108cms.posts.sync(postId, tableName, ids: number[]): Promise<void>109110// Update & Destroy111cms.posts.update(id: number, data: Partial<PostUpdate>): Promise<PostJsonResponse>112cms.posts.destroy(id: number): Promise<boolean>113cms.posts.bulkDestroy(ids: number[]): Promise<number>114```115116## Authors API117118```typescript119cms.authors.findOrCreate(data: AuthorData): Promise<AuthorJsonResponse>120cms.authors.store(data: NewAuthor): Promise<AuthorJsonResponse>121cms.authors.findByEmail(email: string): Promise<AuthorJsonResponse | undefined>122cms.authors.findByName(name: string): Promise<AuthorJsonResponse | undefined>123cms.authors.findByUserId(userId: number): Promise<AuthorJsonResponse | undefined>124cms.authors.fetchAll(): Promise<AuthorJsonResponse[]>125cms.authors.fetchById(id: number): Promise<AuthorJsonResponse | undefined>126cms.authors.update(id, data): Promise<AuthorJsonResponse>127cms.authors.destroy(id): Promise<boolean>128```129130## Tags API131132```typescript133cms.tags.findOrCreateMany(names: string[], taggableType: string): Promise<number[]>134cms.tags.firstOrCreate(name: string, taggableType: string): Promise<TaggableTable>135cms.tags.fetchTags(): Promise<TaggableTable[]>136cms.tags.fetchTagById(id: number): Promise<TaggableTable | undefined>137cms.tags.countTaggedPosts(taggableType: string): Promise<number>138cms.tags.findMostUsedTag(taggableType?: string): Promise<{ name: string, count: number } | null>139cms.tags.fetchTagsWithPostCounts(): Promise<Array<{ name: string, postCount: number }>>140cms.tags.fetchTagDistribution(): Promise<Array<{ name: string, count: number, percentage: number }>>141```142143## Comments API144145```typescript146cms.comments.createComment(data: CreateCommentInput): Promise<CommentablesTable>147cms.comments.updateComment(id: number, input: UpdateCommentInput): Promise<CommentablesTable>148cms.comments.approveComment(id: number): Promise<CommentablesTable>149cms.comments.rejectComment(id: number): Promise<CommentablesTable>150cms.comments.deleteComment(id: number): Promise<void>151```152153## Routes154155### CMS Admin Routes156| Method | Path | Action |157|--------|------|--------|158| GET | `/cms/posts` | PostIndexAction |159| GET | `/cms/posts/{id}` | PostShowAction |160| POST | `/cms/posts` | PostStoreAction |161| PATCH | `/cms/posts/{id}` | PostUpdateAction |162| DELETE | `/cms/posts/{id}` | PostDestroyAction |163| PATCH | `/cms/posts/{id}/views` | PostViewsUpdateAction |164| CRUD | `/cms/authors/*` | Author CRUD |165| CRUD | `/cms/categories/*` | Categorizable CRUD |166| CRUD | `/cms/tags/*` | Taggable CRUD |167| CRUD | `/cms/comments/*` | Comment CRUD |168| CRUD | `/cms/pages/*` | Page CRUD |169170### Public Blog Routes171| Method | Path | Description |172|--------|------|-------------|173| GET | `/blog/posts` | Public post listing |174| GET | `/blog/posts/{id}` | Public post detail |175| GET | `/blog/categories` | Public categories |176| GET | `/blog/tags` | Public tags |177| GET | `/blog/feed.xml` | RSS 2.0 feed (20 recent) |178| GET | `/blog/sitemap.xml` | XML sitemap for SEO |179180## Blog Configuration (config/blog.ts)181182```typescript183{184 subdomain: 'blog',185 title: 'Stacks Blog',186 description: 'The official Stacks.js blog',187 postsPerPage: 10,188 enableComments: true, // declared, NOT yet honoured by the static builder189 enableRss: true, // generates feed.xml190 enableSitemap: true, // generates sitemap.xml191 enableSearch: true, // declared, NOT yet honoured by the static builder192 social: { twitter: '@stacksjs', github: 'stacksjs/stacks' },193 theme: { primaryColor: '#3451b2', logo: '/images/logos/logo-transparent.svg' },194}195```196197## Database Tables198199| Table | Purpose |200|-------|---------|201| `posts` | Blog posts |202| `authors` | Content creators |203| `pages` | Static pages |204| `comments` | Comments (polymorphic) |205| `tags` | Tag definitions |206| `taggable_models` | Polymorphic pivot: tag ↔ model |207| `categorizables` | Category definitions |208| `categorizable_models` | Polymorphic pivot: category ↔ model |209210## Gotchas211- **Polymorphic relations** — categories, tags, and comments use `*_type` fields to support multiple model types212- **Post `content` maps from `body`** — the model attribute is `content` but the DB column mapping comes from `body`213- **Author uses findOrCreate** — `PostStoreAction` auto-creates authors if they don't exist214- **Post store auto-attaches** — creating a post with category/tag data automatically calls `attach()` on pivot tables215- **Post update uses sync** — updating categories/tags uses `sync()` (detaches removed, attaches new)216- **Views increment is atomic** — `PATCH /cms/posts/{id}/views` increments by 1217- **RSS returns 20 items** — hardcoded to 20 most recent published posts218- **Sitemap priorities** — posts 0.8, categories 0.6, blog homepage 0.9219- **Comment status flow** — starts `pending`, can be approved, rejected (→ spam), or trashed