@contentrain/skills 0.1.0

package/frameworks/next.md

@@ -0,0 +1,296 @@
+# Contentrain + Next.js 14+ (App Router)
+
+> Framework guide for consuming Contentrain-managed content in Next.js applications using the App Router.
+
+---
+
+## 1. Setup
+
+### 1.1 SDK Installation
+
+```bash
+pnpm add @contentrain/query   # or npm/yarn
+npx contentrain generate
+```
+
+The generator reads `.contentrain/models/` and produces a typed client in `.contentrain/client/`. Your `package.json` must include the subpath import:
+
+```json
+{
+  "imports": {
+    "#contentrain": {
+      "types": "./.contentrain/client/index.d.ts",
+      "import": "./.contentrain/client/index.mjs",
+      "require": "./.contentrain/client/index.cjs",
+      "default": "./.contentrain/client/index.mjs"
+    }
+  }
+}
+```
+
+The generator adds this automatically. Restart the Next.js dev server after initial generation.
+
+### 1.2 Watch Mode
+
+Run the generator alongside Next.js dev:
+
+```bash
+npx contentrain generate --watch &
+npx next dev
+```
+
+---
+
+## 2. Imports
+
+All SDK functions are imported from the `#contentrain` subpath:
+
+```ts
+import { query, singleton, dictionary, document } from '#contentrain'
+```
+
+This import works in React Server Components, server actions, route handlers, and `generateStaticParams`. The SDK reads JSON files from the file system — no runtime API calls.
+
+---
+
+## 3. Querying Content
+
+### 3.1 Collections
+
+```ts
+const posts = query('blog-post').locale('en').all()
+const featured = query('blog-post').locale('en').where('featured', true).all()
+const sorted = query('blog-post').locale('en').sort('publishedAt', 'desc').all()
+const post = query('blog-post').locale('en').where('id', 'abc-123').first()
+```
+
+### 3.2 Singletons
+
+```ts
+const hero = singleton('hero').locale('en').get()
+```
+
+### 3.3 Dictionaries
+
+```ts
+const label = dictionary('ui-labels').locale('en').get('submit_button')
+const allLabels = dictionary('ui-labels').locale('en').get()
+```
+
+### 3.4 Documents
+
+```ts
+const article = document('blog-article').locale('en').bySlug('getting-started')
+```
+
+### 3.5 Relations
+
+```ts
+const posts = query('blog-post').locale('en').include('author', 'tags').all()
+// post.author → full author object
+// post.tags → array of full tag objects
+```
+
+---
+
+## 4. App Router Integration
+
+### 4.1 React Server Components
+
+SDK calls work directly in Server Components — no `use` wrapper, no `useEffect`, no client-side fetching:
+
+```tsx
+// app/blog/page.tsx
+import { query } from '#contentrain'
+
+export default async function BlogPage() {
+  const posts = query('blog-post').locale('en').sort('publishedAt', 'desc').all()
+
+  return (
+    <ul>
+      {posts.map(post => (
+        <li key={post.id}>{post.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+### 4.2 Dynamic Routes with Locale
+
+For `app/[locale]/blog/[slug]/page.tsx`:
+
+```tsx
+import { document } from '#contentrain'
+
+interface Props {
+  params: Promise<{ locale: string; slug: string }>
+}
+
+export default async function PostPage({ params }: Props) {
+  const { locale, slug } = await params
+  const post = document('blog-article').locale(locale).bySlug(slug)
+
+  return (
+    <article>
+      <h1>{post.title}</h1>
+      <div>{post.body}</div>
+    </article>
+  )
+}
+```
+
+### 4.3 Static Params Generation
+
+Pre-generate all content pages at build time:
+
+```tsx
+import { query } from '#contentrain'
+
+export async function generateStaticParams() {
+  const posts = query('blog-post').locale('en').all()
+  return posts.map(post => ({ slug: post.slug }))
+}
+```
+
+For multi-locale static generation:
+
+```tsx
+import { query } from '#contentrain'
+
+const locales = ['en', 'tr', 'de']
+
+export async function generateStaticParams() {
+  const params = []
+  for (const locale of locales) {
+    const posts = query('blog-post').locale(locale).all()
+    for (const post of posts) {
+      params.push({ locale, slug: post.slug })
+    }
+  }
+  return params
+}
+```
+
+### 4.4 Route Handlers
+
+SDK works in route handlers for API-style access:
+
+```ts
+// app/api/posts/route.ts
+import { query } from '#contentrain'
+import { NextResponse } from 'next/server'
+
+export function GET() {
+  const posts = query('blog-post').locale('en').all()
+  return NextResponse.json(posts)
+}
+```
+
+### 4.5 Client Components
+
+Client Components cannot import `#contentrain` directly (it reads from the file system). Fetch data in a Server Component and pass it as props:
+
+```tsx
+// Server Component
+import { singleton } from '#contentrain'
+import HeroClient from './HeroClient'
+
+export default async function HeroSection() {
+  const hero = singleton('hero').locale('en').get()
+  return <HeroClient data={hero} />
+}
+```
+
+---
+
+## 5. i18n Integration
+
+### 5.1 With next-intl
+
+```tsx
+import { query } from '#contentrain'
+import { getLocale } from 'next-intl/server'
+
+export default async function BlogPage() {
+  const locale = await getLocale()
+  const posts = query('blog-post').locale(locale).all()
+  // ...
+}
+```
+
+### 5.2 With Built-in i18n Routing
+
+Use the `[locale]` route segment to determine the active locale, then pass it to SDK calls. Contentrain dictionaries can supplement or replace `next-intl` message files for content-driven strings.
+
+---
+
+## 6. Markdown and MDX
+
+### 6.1 Document Body Rendering
+
+For document-kind entries with markdown bodies, use `next-mdx-remote` or a markdown renderer:
+
+```tsx
+import { document } from '#contentrain'
+import { MDXRemote } from 'next-mdx-remote/rsc'
+
+export default async function DocPage({ params }: Props) {
+  const { slug } = await params
+  const doc = document('doc-page').locale('en').bySlug(slug)
+
+  return (
+    <article>
+      <h1>{doc.title}</h1>
+      <MDXRemote source={doc.body} />
+    </article>
+  )
+}
+```
+
+### 6.2 Custom Components in MDX
+
+Pass custom component mappings to the MDX renderer to control how markdown elements render in your design system.
+
+---
+
+## 7. Build and Deployment
+
+### 7.1 Static Export
+
+Contentrain content is fully static. Use `output: 'export'` in `next.config.js` for full static generation:
+
+```js
+// next.config.js
+module.exports = {
+  output: 'export'
+}
+```
+
+### 7.2 ISR and Server Mode
+
+In server mode, SDK calls execute at request time (or at build time for statically generated pages). Content is still file-based — no external API dependency. Redeploy to pick up content changes.
+
+### 7.3 Deployment Flow
+
+1. Content changes are committed to Git via MCP tools.
+2. Push triggers platform rebuild (Vercel, Netlify).
+3. `next build` runs, SDK reads `.contentrain/` content.
+4. Static pages are generated with embedded content.
+
+---
+
+## 8. Type Safety
+
+The generated client provides full TypeScript types:
+
+```tsx
+import { query } from '#contentrain'
+
+// Fully typed — autocomplete for all fields
+const posts = query('blog-post').locale('en').all()
+posts[0].title    // string
+posts[0].author   // Author type when using .include('author')
+```
+
+Keep the generator running in watch mode during development to stay in sync with model changes.

package/frameworks/node.md

@@ -0,0 +1,63 @@
+# Contentrain + Node.js
+
+> Framework guide for direct server-side use of the generated Contentrain client.
+
+---
+
+## 1. ESM Usage
+
+For ESM apps, import from `#contentrain` directly:
+
+```ts
+import { query, singleton, dictionary, document } from '#contentrain'
+
+const hero = singleton('hero').locale('en').get()
+const posts = query('blog-post').locale('en').all()
+const labels = dictionary('ui-labels').locale('en').get()
+const article = document('blog-article').locale('en').bySlug('getting-started')
+```
+
+This is the correct path for:
+
+- modern Node ESM apps
+- server scripts
+- Express/Fastify codebases running as ESM
+
+## 2. CommonJS Usage
+
+For CommonJS consumers, initialize first:
+
+```js
+async function run() {
+  const client = await require('#contentrain').init()
+  const hero = client.singleton('hero').locale('en').get()
+  const posts = client.query('blog-post').locale('en').all()
+  return { hero, posts }
+}
+```
+
+Use this pattern for:
+
+- NestJS
+- legacy CommonJS servers
+- mixed CJS toolchains
+
+## 3. Express Example
+
+```ts
+import express from 'express'
+import { query } from '#contentrain'
+
+const app = express()
+
+app.get('/api/posts', (_req, res) => {
+  res.json(query('blog-post').locale('en').all())
+})
+```
+
+## 4. Rules
+
+- ESM: direct `import` from `#contentrain`
+- CJS: `await require('#contentrain').init()`
+- do not expect runtime writes; this is generated static content access
+

package/frameworks/nuxt.md

@@ -0,0 +1,274 @@
+# Contentrain + Nuxt 3
+
+> Framework guide for consuming Contentrain-managed content in Nuxt 3 applications.
+
+---
+
+## 1. Setup
+
+### 1.1 SDK Installation
+
+```bash
+pnpm add @contentrain/query   # or npm/yarn
+npx contentrain generate
+```
+
+The generator reads `.contentrain/models/` and produces a typed client in `.contentrain/client/`. Your `package.json` must include the subpath import:
+
+```json
+{
+  "imports": {
+    "#contentrain": {
+      "types": "./.contentrain/client/index.d.ts",
+      "import": "./.contentrain/client/index.mjs",
+      "require": "./.contentrain/client/index.cjs",
+      "default": "./.contentrain/client/index.mjs"
+    }
+  }
+}
+```
+
+The generator adds this automatically. After generation, restart the Nuxt dev server to pick up the new import map.
+
+### 1.2 Watch Mode
+
+Run the generator in watch mode alongside Nuxt dev:
+
+```bash
+npx contentrain generate --watch &
+npx nuxt dev
+```
+
+Any model or content change under `.contentrain/` triggers client regeneration automatically.
+
+---
+
+## 2. Imports
+
+All SDK functions are imported from the `#contentrain` subpath:
+
+```ts
+import { query, singleton, dictionary, document } from '#contentrain'
+```
+
+Treat this import as **server-only** in Nuxt. Use it in Nitro server routes, server utilities, route middleware, and other server execution contexts. Do **not** import `#contentrain` directly in client-rendered Vue components or generic `<script setup>` blocks.
+
+---
+
+## 3. Querying Content
+
+### 3.1 Collections
+
+Collections return arrays. The SDK converts the internal object-map storage to arrays automatically.
+
+```ts
+const posts = query('blog-post').locale('en').all()
+const featured = query('blog-post').locale('en').where('featured', true).all()
+const sorted = query('blog-post').locale('en').sort('publishedAt', 'desc').all()
+```
+
+Single entry by ID:
+
+```ts
+const post = query('blog-post').locale('en').where('id', 'abc-123').first()
+```
+
+### 3.2 Singletons
+
+Singletons return a single object. Use `.get()` instead of `.all()`.
+
+```ts
+const hero = singleton('hero').locale('en').get()
+```
+
+### 3.3 Dictionaries
+
+Dictionaries provide key-value access for UI strings.
+
+```ts
+const labels = dictionary('ui-labels').locale('en').get('submit_button')
+const allLabels = dictionary('ui-labels').locale('en').get()
+```
+
+### 3.4 Documents
+
+Documents are long-form content with metadata and a body field (markdown or MDX).
+
+```ts
+const article = document('blog-article').locale('en').bySlug('getting-started')
+const docs = document('doc-page').locale('en').all()
+```
+
+### 3.5 Relations
+
+Resolve relation fields to full objects with `.include()`:
+
+```ts
+const posts = query('blog-post').locale('en').include('author', 'tags').all()
+// post.author → full author object instead of just the ID
+// post.tags → array of full tag objects
+```
+
+---
+
+## 4. Nuxt Integration Patterns
+
+### 4.1 Page Data Loading
+
+Load content through a server route, then consume it with `useAsyncData` in the page:
+
+```ts
+// server/api/blog-posts.get.ts
+import { query } from '#contentrain'
+import { getQuery } from 'h3'
+
+export default defineEventHandler((event) => {
+  const locale = getQuery(event).locale?.toString() ?? 'en'
+  return query('blog-post').locale(locale).sort('publishedAt', 'desc').all()
+})
+```
+
+```vue
+<script setup lang="ts">
+const { data: posts } = await useAsyncData('blog-posts', () => $fetch('/api/blog-posts'))
+</script>
+```
+
+### 4.2 Dynamic Routes
+
+For `pages/blog/[slug].vue`:
+
+```vue
+<script setup lang="ts">
+const route = useRoute()
+const { data: post } = await useAsyncData(
+  `post-${route.params.slug}`,
+  () => $fetch(`/api/blog-post/${route.params.slug}`),
+)
+</script>
+```
+
+With the matching server route:
+
+```ts
+// server/api/blog-post/[slug].get.ts
+import { document } from '#contentrain'
+import { getRouterParam } from 'h3'
+
+export default defineEventHandler((event) => {
+  const slug = getRouterParam(event, 'slug')
+  return document('blog-article').locale('en').bySlug(slug ?? '')
+})
+```
+
+### 4.3 Server Routes
+
+Content is also accessible in Nuxt server routes (`server/api/`):
+
+```ts
+// server/api/posts.get.ts
+import { query } from '#contentrain'
+
+export default defineEventHandler(() => {
+  return query('blog-post').locale('en').all()
+})
+```
+
+---
+
+## 5. i18n Integration
+
+### 5.1 With @nuxtjs/i18n
+
+Use the `useI18n()` composable to get the current locale, then pass it to SDK calls:
+
+```vue
+<script setup lang="ts">
+const { locale } = useI18n()
+const { data: posts } = await useAsyncData(
+  `posts-${locale.value}`,
+  () => $fetch('/api/blog-posts', { query: { locale: locale.value } }),
+  { watch: [locale] }
+)
+</script>
+```
+
+### 5.2 Dictionary Strings as i18n Source
+
+Contentrain dictionaries can serve as the i18n message source. Export dictionary content and feed it to `@nuxtjs/i18n` via a custom loader, or use SDK calls directly in components for content-driven strings.
+
+---
+
+## 6. Markdown and Document Content
+
+### 6.1 Nuxt Content Module
+
+If using `@nuxt/content`, point it to `.contentrain/content/` for markdown files:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  content: {
+    sources: {
+      contentrain: {
+        driver: 'fs',
+        base: '.contentrain/content'
+      }
+    }
+  }
+})
+```
+
+### 6.2 Rendering Document Bodies
+
+For document-kind entries, the `body` field contains markdown. Render it with `@nuxt/content` or any markdown renderer:
+
+```vue
+<template>
+  <ContentRenderer :value="parsedBody" />
+</template>
+```
+
+---
+
+## 7. Static Generation and Deployment
+
+### 7.1 Static Generation
+
+Contentrain content is file-based. `nuxt generate` reads all content at build time:
+
+```bash
+npx nuxt generate
+```
+
+All SDK calls resolve to static JSON reads — no runtime API calls during generation.
+
+### 7.2 Deployment
+
+Content lives in Git. The deployment flow:
+
+1. Author or agent creates/updates content via MCP tools.
+2. Changes are committed to a branch and reviewed.
+3. After merge, push triggers platform rebuild (Vercel, Netlify, Cloudflare Pages).
+4. `nuxt generate` runs, SDK reads `.contentrain/` content, static site is produced.
+
+### 7.3 Hybrid Rendering
+
+For SSR pages, SDK calls execute on the server at request time. Content is still read from the file system — no external API dependency.
+
+---
+
+## 8. Type Safety
+
+The generated client includes full TypeScript types for every model:
+
+```ts
+import { query } from '#contentrain'
+
+// Fully typed — IDE autocomplete for field names, return types
+const posts = query('blog-post').locale('en').all()
+// posts[0].title — string
+// posts[0].author — Author (when using .include('author'))
+```
+
+Type definitions are regenerated whenever models change. Keep the generator running in watch mode during development.

package/frameworks/react-native.md

@@ -0,0 +1,80 @@
+# Contentrain + React Native
+
+> Framework guide for bare React Native / Metro consumers of the generated Contentrain client.
+
+---
+
+## 1. Setup
+
+```bash
+pnpm add @contentrain/query
+npx contentrain generate
+```
+
+React Native uses the generated CommonJS bootstrap path. Do not expect direct ESM `#contentrain` imports inside Metro components.
+
+---
+
+## 2. Bootstrap the Client Once
+
+Create a small loader module:
+
+```ts
+// src/contentrain.ts
+let clientPromise: Promise<any> | null = null
+
+export function getContentrainClient() {
+  if (!clientPromise) {
+    clientPromise = require('#contentrain').init()
+  }
+  return clientPromise
+}
+```
+
+This ensures the generated client is initialized once and reused across screens.
+
+---
+
+## 3. Use It in Screens
+
+```tsx
+import { useEffect, useState } from 'react'
+import { Text, View } from 'react-native'
+import { getContentrainClient } from './contentrain'
+
+export function HomeScreen() {
+  const [heroTitle, setHeroTitle] = useState('')
+
+  useEffect(() => {
+    getContentrainClient().then((client) => {
+      setHeroTitle(client.singleton('hero').locale('en').get().title)
+    })
+  }, [])
+
+  return (
+    <View>
+      <Text>{heroTitle}</Text>
+    </View>
+  )
+}
+```
+
+Collections and dictionaries work the same way:
+
+```ts
+getContentrainClient().then((client) => {
+  const posts = client.query('blog-post').locale('en').all()
+  const labels = client.dictionary('ui-labels').locale('en').get()
+})
+```
+
+---
+
+## 4. Rules
+
+- initialize with `require('#contentrain').init()`
+- cache the promise; do not initialize in every component render
+- treat the generated client as static read-only data
+- re-run `contentrain generate` after model or content changes
+
+If the project is Expo-based, use the dedicated Expo guide. The runtime pattern is similar, but Expo-specific tooling and structure differ.