TEMPLATE SYSTEM QUICKSTART - nself-org/nchat GitHub Wiki

Template System - Quick Start Guide

Version: 1.0.0 Date: 2026-02-03


Overview

The Ι³Chat template system allows you to instantly transform your chat application to mimic popular platforms like WhatsApp, Telegram, Slack, or Discord. Each template includes:

  • Complete UI redesign
  • Platform-specific features
  • Custom terminology
  • Authentic color schemes
  • Component overrides

Quick Examples

1. Use Template System (Most Common)

import { useTemplate } from '@/templates/hooks/use-template'

function MyComponent() {
  const {
    template, // Current template object
    templateId, // 'default' | 'whatsapp' | 'telegram' | 'slack' | 'discord'
    colors, // Theme colors
    features, // Feature config
    terminology, // Custom labels
    switchTemplate, // Function to switch templates
  } = useTemplate()

  return (
    <div style={{ backgroundColor: colors.surfaceColor }}>
      <h1>{template.name}</h1>
    </div>
  )
}

2. Switch Templates

import { useTemplate } from '@/templates/hooks/use-template'

function TemplateSwitcher() {
  const { switchTemplate, templateId, isLoading } = useTemplate()

  return (
    <select
      value={templateId}
      onChange={(e) => switchTemplate(e.target.value)}
      disabled={isLoading}
    >
      <option value="default">Ι³Chat</option>
      <option value="whatsapp">WhatsApp</option>
      <option value="telegram">Telegram</option>
      <option value="slack">Slack</option>
      <option value="discord">Discord</option>
    </select>
  )
}

3. Use Theme Colors

import { useThemeColors } from '@/templates/hooks/use-template'

function Card() {
  const colors = useThemeColors()

  return (
    <div
      style={{
        backgroundColor: colors.cardColor,
        color: colors.textColor,
        border: `1px solid ${colors.borderColor}`,
      }}
    >
      <h2 style={{ color: colors.primaryColor }}>Title</h2>
      <p style={{ color: colors.textMutedColor }}>Description</p>
    </div>
  )
}

4. Check Features

import { useFeature } from '@/templates/hooks/use-template'

function ThreadButton({ messageId }) {
  const hasThreads = useFeature('threads')

  // Hide button if template doesn't support threads
  if (!hasThreads) return null

  return <button onClick={() => openThread(messageId)}>Reply in thread</button>
}

5. Use Terminology

import { useTerminology } from '@/templates/hooks/use-template'

function CreateChannelButton() {
  const { t } = useTerminology()

  return (
    <button>
      {t('createChannel')}
      {/*
        Returns:
        - "Create Channel" for Ι³Chat/Slack/Discord
        - "New Chat" for WhatsApp
        - "New Chat" for Telegram
      */}
    </button>
  )
}

Environment Configuration

Set template via environment variable:

# .env.local
NEXT_PUBLIC_PLATFORM_TEMPLATE=whatsapp

Override template settings:

# .env.local
NEXT_PUBLIC_PLATFORM_TEMPLATE=slack
NEXT_PUBLIC_THEME_MODE=dark
NEXT_PUBLIC_SIDEBAR_POSITION=right
NEXT_PUBLIC_SIDEBAR_WIDTH=280
NEXT_PUBLIC_MESSAGE_DENSITY=compact
NEXT_PUBLIC_THEME_PRIMARY=#4A154B

Available Templates

1. Ι³Chat (default)

Best For: Teams wanting full features

Theme: Cyan/Blue (#00D4FF) Mode: Dark

Features:

  • βœ… All features enabled
  • βœ… Threads (panel)
  • βœ… Voice channels
  • βœ… E2E encryption
  • βœ… Bots & webhooks

2. WhatsApp

Best For: Personal/small teams

Theme: Green (#25D366) Mode: Light

Features:

  • βœ… Chat bubbles
  • βœ… Double-check receipts (βœ“βœ“)
  • βœ… Voice messages
  • βœ… Status/Stories
  • ❌ No threads
  • ❌ No public channels

3. Telegram

Best For: Large communities

Theme: Blue (#0088CC) / Purple (#8774E1) dark Mode: System

Features:

  • βœ… Chat folders
  • βœ… Secret chats
  • βœ… Bots
  • βœ… Scheduled messages
  • βœ… Polls & quizzes
  • ❌ No voice channels

4. Slack

Best For: Professional teams

Theme: Aubergine (#4A154B) Mode: System

Features:

  • βœ… Thread panel
  • βœ… Workspace switcher
  • βœ… Huddles
  • βœ… App integrations
  • βœ… Workflows
  • ❌ No voice channels

5. Discord

Best For: Gaming/large groups

Theme: Blurple (#5865F2) Mode: Dark

Features:

  • βœ… Server list
  • βœ… Voice channels
  • βœ… Role colors
  • βœ… Rich embeds
  • βœ… Member list
  • ❌ No stories

Common Use Cases

1. Conditional Rendering Based on Features

function MessageActions({ message }) {
  const { features } = useTemplate()

  return (
    <div>
      {features.threads && <ThreadButton />}
      {features.reactions && <ReactButton />}
      {features.voiceMessages && <VoiceButton />}
      {features.codeBlocks && <CodeButton />}
    </div>
  )
}

2. Use Template-Specific Components

function Message({ message }) {
  const { template } = useTemplate()

  // Use template-specific message component if available
  const MessageComponent = template.components?.MessageItem ?? DefaultMessage

  return <MessageComponent {...message} />
}

3. Apply Template Colors Dynamically

function StatusBadge({ status }) {
  const colors = useThemeColors()

  const bgColor = {
    online: colors.successColor,
    away: colors.warningColor,
    offline: colors.errorColor,
  }[status]

  return (
    <span
      style={{
        backgroundColor: bgColor,
        color: 'white',
        padding: '4px 8px',
        borderRadius: '4px',
      }}
    >
      {status}
    </span>
  )
}

4. Theme Preview Mode

function TemplatePreview() {
  const { switchTemplate, templateId } = useTemplate()
  const [originalTemplate, setOriginalTemplate] = useState(templateId)

  const handlePreview = async (id) => {
    setOriginalTemplate(templateId)
    await switchTemplate(id)
  }

  const handleRevert = async () => {
    await switchTemplate(originalTemplate)
  }

  return (
    <div>
      <button onClick={() => handlePreview('whatsapp')}>Preview WhatsApp</button>
      <button onClick={handleRevert}>Revert</button>
    </div>
  )
}

API Reference

useTemplate()

Main hook for accessing template system.

const {
  template, // PlatformTemplate | null
  templateId, // TemplateId
  isLoading, // boolean
  error, // Error | null
  theme, // 'light' | 'dark'
  setTheme, // (theme: 'light' | 'dark' | 'system') => void
  colors, // ThemeColors
  layout, // LayoutConfig
  features, // FeatureConfig
  isFeatureEnabled, // (feature: keyof FeatureConfig) => boolean
  terminology, // TerminologyConfig
  t, // (key: keyof TerminologyConfig) => string
  switchTemplate, // (templateId: TemplateId) => Promise<void>
  applyOverrides, // (overrides: PartialTemplate) => void
} = useTemplate()

useThemeColors()

Get theme colors only.

const colors: ThemeColors = useThemeColors()

useFeature(feature)

Check if a specific feature is enabled.

const hasThreads: boolean = useFeature('threads')
const hasVoiceMessages: boolean = useFeature('voiceMessages')

useTerminology()

Get terminology translation function.

const { terminology, t } = useTerminology()

// Get translated term
const label = t('channel') // "Channel" or "Chat"
const plural = t('channelPlural') // "Channels" or "Chats"

loadTemplate(id)

Load a template programmatically.

import { loadTemplate } from '@/templates'

const template = await loadTemplate('whatsapp')

customizeTemplate(base, overrides)

Create a customized template.

import { customizeTemplate } from '@/templates'

const custom = customizeTemplate(baseTemplate, {
  theme: {
    light: { primaryColor: '#FF0000' },
  },
  layout: {
    sidebarWidth: 320,
  },
})

Color Properties

All templates include these 16 color properties:

Property Description
primaryColor Main brand color
secondaryColor Secondary brand color
accentColor Accent/highlight color
backgroundColor Main background
surfaceColor Cards/elevated surfaces
cardColor Card backgrounds
popoverColor Popovers/dropdowns
textColor Primary text
textMutedColor Secondary text
textInverseColor Text on primary backgrounds
borderColor Default borders
borderMutedColor Subtle borders
buttonPrimaryBg Primary button background
buttonPrimaryText Primary button text
buttonSecondaryBg Secondary button background
buttonSecondaryText Secondary button text
successColor Success messages
warningColor Warning messages
errorColor Error messages
infoColor Info messages
linkColor Hyperlinks
focusRingColor Focus indicators
selectionBg Text selection
highlightBg Highlighted text

Feature Flags

Common features you can check:

Feature WhatsApp Telegram Slack Discord
threads ❌ ❌ βœ… βœ…
reactions βœ… βœ… βœ… βœ…
voiceMessages βœ… βœ… ❌ ❌
codeBlocks ❌ βœ… βœ… βœ…
markdown ❌ βœ… βœ… βœ…
gifPicker βœ… βœ… βœ… βœ…
typing βœ… βœ… βœ… βœ…
readReceipts βœ… βœ… ❌ ❌
presence βœ… βœ… βœ… βœ…

Terminology Mapping

Key Ι³Chat/Slack WhatsApp Telegram Discord
workspace Workspace WhatsApp Telegram Server
channel Channel Chat Chat Channel
directMessage Direct Message Chat Chat Direct Message
thread Thread Reply Reply Thread
member Member Participant Member Member
createChannel Create Channel New Chat New Chat Create Channel

Admin UI Components

Theme Editor

import { ThemeEditor } from '@/components/admin/theme-editor'
;<ThemeEditor
  onSave={(colors) => console.log('Saved', colors)}
  onExport={(colors) => console.log('Exported', colors)}
/>

Template Gallery

import { TemplateGallery } from '@/components/admin/template-gallery'
;<TemplateGallery />

Troubleshooting

Template not loading

// Check if template exists
const templates = getAvailableTemplates()
console.log(
  'Available:',
  templates.map((t) => t.id)
)

// Check current template
const { template, error } = useTemplate()
if (error) console.error('Template error:', error)

Colors not applying

// Ensure TemplateProvider wraps your app
import { TemplateProvider } from '@/templates/hooks/use-template'

<TemplateProvider>
  <YourApp />
</TemplateProvider>

// Check if CSS variables are generated
const style = document.documentElement.style
console.log('Primary:', style.getPropertyValue('--primary'))

Feature not working

// Check if feature is enabled
const { isFeatureEnabled } = useTemplate()
console.log('Threads enabled:', isFeatureEnabled('threads'))

// Get feature config
const { features } = useTemplate()
console.log('Thread style:', features.threadStyle) // 'panel' | 'inline' | 'popup'

Best Practices

  1. Always wrap app in TemplateProvider

    <TemplateProvider>
      <App />
    </TemplateProvider>
  2. Use hooks instead of direct imports

    // βœ… Good
    const colors = useThemeColors()
    
    // ❌ Bad
    import { colors } from '@/templates/whatsapp/config'
  3. Check features before rendering

    // βœ… Good
    {
      hasThreads && <ThreadButton />
    }
    
    // ❌ Bad
    ;<ThreadButton /> // Will always render
  4. Use terminology for labels

    // βœ… Good
    const { t } = useTerminology()
    <button>{t('createChannel')}</button>
    
    // ❌ Bad
    <button>Create Channel</button> // Hardcoded
  5. Prefer CSS variables over inline styles

    // βœ… Good
    <div className="bg-surface text-foreground">
    
    // ❌ Bad
    <div style={{ backgroundColor: colors.surfaceColor }}>

Resources

  • Documentation: /Users/admin/Sites/nself-chat/docs/WHITE-LABEL-TEMPLATES-COMPLETE.md
  • Implementation: /Users/admin/Sites/nself-chat/docs/TASKS-109-113-COMPLETE.md
  • Types: /Users/admin/Sites/nself-chat/src/templates/types.ts
  • Presets: /Users/admin/Sites/nself-chat/src/lib/theme-presets.ts

Quick Start Guide v1.0.0 Last Updated: 2026-02-03

⚠️ **GitHub.com Fallback** ⚠️