Overview

XenT uses a simple configuration system that makes theme updates easy. As an npm package, the theme handles all defaults internally, and you only need to configure what you want to customize.

Quick Start

Only edit this file: user.config.ts (in your project root)

That’s it! All other config files are managed automatically.

File Structure

your-project/
├── user.config.ts  [EDIT] (your settings)
├── astro.config.ts [EDIT] (integrates XenT theme)
└── node_modules/xent-theme/ [READONLY] (theme package)

How the Configuration System Works

1. Theme Defaults (internal to npm package) - Contains all theme settings
2. Your Config (user.config.ts) - Only what you want to customize
3. Auto Merge (handled by Astro integration) - Combines them automatically

This separation ensures that:

• Theme updates don’t overwrite your settings
• You only need to specify what you want to change
• Configuration validation catches errors early
• Backwards compatibility is maintained

For New Users

If you’re setting up XenT for the first time, simply edit src/config/user-config.ts - that’s it! The file contains comprehensive examples and documentation for all available options.

Configuration Example

Here’s what a typical user configuration looks like:

// user-config.ts
export const USER_CONFIG: UserConfig = {
  site: {
    title: 'My Blog',
    description: 'Welcome to my site',
    author: 'Your Name',
    url: 'https://yoursite.com',
  },

  ui: {
    theming: {
      default: 'nord', // Available: 'auto', 'light', 'dark', 'nord', 'gruvbox'
    },
  },

  features: {
    comments: {
      enable: true,
      isso: {
        enable: true,
        server: 'https://comments.yoursite.com',
      },
    },
  },
};

Theme Updates

When the theme updates:

1. Safe: Your user-config.ts stays unchanged
2. Automatic: New features get default settings
3. Compatible: Your customizations still work

Backwards Compatibility

Old imports still work:

import config from '@/config'; // Works
import { siteConfig } from '@/config'; // Works
import { uiConfig } from '@/config'; // Works

What Can You Customize?

Check user-config.ts for all available options with examples and comments!

For Existing Users (Migration Required)

If you’ve already customized XenT with the old configuration system, follow this guide to migrate your settings to the new layered approach.

Step 1: Backup Your Current Config

First, create backups of your existing configuration files:

# Backup your existing configurations
cp src/config/site.ts ~/xent-site-backup.ts
cp src/config/ui.ts ~/xent-ui-backup.ts
cp src/config/features.ts ~/xent-features-backup.ts
cp src/config/social.ts ~/xent-social-backup.ts

Step 2: Extract Your Customizations

Open src/config/user-config.ts and add your customized settings. Here’s how to migrate different configuration sections:

Site Settings Migration

// OLD: src/config/site.ts
export const siteConfig: SiteConfig = {
  title: 'My Blog',
  description: 'My awesome site',
  author: 'John Doe',
  url: 'https://mysite.com',
  // ... other settings
};

// NEW: src/config/user-config.ts
export const USER_CONFIG: UserConfig = {
  site: {
    title: 'My Blog',
    description: 'My awesome site',
    author: 'John Doe',
    url: 'https://mysite.com',
    // Only include what you customized
  },
};

UI Settings Migration

// OLD: src/config/ui.ts
export const uiConfig = {
  theming: {
    default: 'dark',
  },
  sidebar: {
    position: 'right',
  },
  // ...
};

// NEW: src/config/user-config.ts (add to USER_CONFIG)
export const USER_CONFIG: UserConfig = {
  // ... other sections
  ui: {
    theming: {
      default: 'dark',
    },
    sidebar: {
      position: 'right',
    },
  },
};

Features Migration

// OLD: src/config/features.ts
export const featuresConfig = {
  comments: {
    enable: true,
    isso: {
      server: 'https://comments.mysite.com',
    },
  },
};

// NEW: src/config/user-config.ts (add to USER_CONFIG)
export const USER_CONFIG: UserConfig = {
  // ... other sections
  features: {
    comments: {
      enable: true,
      isso: {
        enable: true,
        server: 'https://comments.mysite.com',
      },
    },
  },
};

Step 3: Test Your Migration

After migrating your settings, test that everything works correctly:

npm run build

If you see any errors, verify that all required fields are present in user-config.ts:

• site.title
• site.description
• site.author
• site.url

Step 4: Clean Up (Optional)

Once everything works properly, you can remove the old backup files:

rm ~/xent-*-backup.ts

Future Updates

With the new layered system, updating XenT is much simpler and safer:

1. Backup: cp src/config/user-config.ts ~/my-config.ts
2. Update: Download new XenT template or pull latest changes
3. Restore: cp ~/my-config.ts src/config/user-config.ts

Your configuration stays safe and separate from theme code!

Advanced Configuration Details

Validation System

The new system includes built-in validation that shows helpful errors:

Configuration Error:
Missing required configuration: site.title
Please check your src/config/user-config.ts file

This prevents broken builds and makes debugging much easier!

Additional Resources

• Configuration Documentation: This guide contains all configuration details
• Examples: Look at src/config/user-config.ts for all available options with examples
• Backwards Compatibility: All old imports still work during the transition period

Need Help?

If you encounter any issues during migration:

1. Check that all required fields are present in your user-config.ts
2. Compare your settings with the examples in the user config file
3. Run npm run build to see any validation errors
4. Refer to the configuration documentation for detailed explanations

The layered configuration system makes XenT much easier to maintain and update while keeping your customizations safe!