Configuration

How to configure the project

Webcore CMS uses two configuration files and a .env file to keep concerns cleanly separated:

webcore.config.scss for CSS and theming
webcore.config.ts for JavaScript and runtime behaviour
.env for environment-specific constants

webcore.config.scss

webcore.config.scss controls everything visual. Fonts, themes, and any CSS customization inherited from the Webcore component library. It lives at the root of your project and is the single source of truth for your site’s appearance. It works exactly like webcore.config.scss in a WebcoreUI project with one addition:

The @setup mixin that you would normally use in your layout, is also used here using a $setup variable. This means that any configuration options you add to the mixin in this file, will be available globally across your project, including the CMS interface. It accepts the same arguments as the @setup mixin in WebcoreUI.

Unlock CMS

// Configuration passed to @setup mixin
// Remove themes you don't want to use to reduce CSS bundle size
// See https://webcoreui.dev/docs/css-configuration
$setup: (
    fontRegular: '/fonts/Inter-Regular.woff2',
    fontBold: '/fonts/Inter-Bold.woff2',
    themes: (
        dark: '.dark',
        light: '.light',
        midnight: '.midnight',
        amber: '.amber',
        nordic: '.nordic',
        vintage: '.vintage',
        synthwave: '.synthwave',
        forest: '.forest'
    )
);

webcore.config.ts

webcore.config.ts is where all runtime configuration lives. Site identity, navigation, permissions, and CMS behaviour. It exports a set of named constants that the CMS reads at build time and runtime. The following variables are available:

Language & favicon

export const lang = 'en'
export const favicon = '/favicon.ico'

lang sets the lang attribute on the <html> element. Accepts any valid BCP 47 language tag. favicon sets the path to the favicon file, relative to public/. Accepts any image format supported by browsers.

Global SEO

export const seo = {
    prefetchGA: true,
    prefetchGTAG: true
}

Global SEO properties applied to every page. Accepts any prop supported by the SEO block.

Menu

export const menu = {
    logo: {
        url: '/img/logo.png',
        width: 25
    },
    items: [
        { name: 'Home', href: '/' },
        { name: 'Blog', href: '/blog' }
    ]
}

Defines the top-level navigation rendered on your site. Accepts any prop supported by the following components, depending on your layout:

Dropdown Navigation

Mega Menu

Footer

export const footer = {
    logo: {
        url: '/img/logo.png',
        width: 25
    },
    columns: [
        {
            title: 'Sitemap',
            items: [
                { href: '/', name: 'Home' },
                { name: 'Blog', href: '/blog' }
            ]
        }
    ],
    subText: `© ${new Date().getFullYear()} Webcore. All Rights Reserved.`
}

Configures the site footer. Accepts any prop from the Footer component.

Themes

export const themes = {
    '#252525': 'dark',
    '#DDD': 'light',
    // ...
}

export const defaultTheme = 'dark'

Controls which themes are available to users in the CMS theme switcher. Keys are the color swatches shown in the UI, values are the theme class names. These must match the theme classes defined in webcore.config.scss. defaultTheme sets the fallback when no user preference has been saved.

Permissions

export const permissions = {
    'content:create': 'Create content',
    'content:read': 'View all content',
    // ...
}

Defines the full set of permission keys available across the CMS, written in resource:action format. These keys are what you assign to roles. The CMS ships with over 20 granular permissions covering content, content types, states, users, and roles, covering both global and own-content-scoped variants for ownership control.

If you need to add custom permissions for your project, define them here. You can reference them in code using the reactive usePermissions:

Unlock CMS

import { usePermission } from '@webcore/hooks'

const hasPermission = usePermission()

// Check for permission in your code
hasPermission('content:create')

The config file also exposes permissionDependencies and permissionExclusions that let you define which permissions automatically imply or conflict with others — the CMS enforces these rules when assigning permissions to roles so that contradictory or incomplete combinations can’t be saved.

Save Debounce

export const saveDebounce = 500

Controls how long the CMS waits (in milliseconds) after a keystroke before committing a change to the database. Lowering this value makes saves feel more immediate but increases the number of API calls. The default of 500ms is a sensible balance for most setups. See debounce for more details.

Block Selector Category Order

export const blockSelectorCategoryOrder = [
    'Components',
    'Blocks'
]

Sets the display order of categories in the block picker when editing a content entry. Any category not listed here will appear after the listed ones, sorted alphabetically.

The above variables are also documented within webcore.config.ts.

Environment Variables

Unlock CMS

# Default admin user used for initial seed — change in CMS before going live
ADMIN_EMAIL=john@doe.com
ADMIN_USER=user
ADMIN_PASS=pass

# Remote database connection (required for dev:prod and build:prod)
ASTRO_DB_REMOTE_URL=
ASTRO_DB_APP_TOKEN=

# Local database path (used by npm run dev and npm run build)
ASTRO_DATABASE_FILE=.astro/content.db

# Public site URL — used for SEO and sitemap generation
SITE=https://example.com

Important

Change the default ADMIN_EMAIL, ADMIN_USER, and ADMIN_PASS in your CMS after the initial seed before deploying to production. The defaults are placeholders and should never be left in a live environment.

Variable	Required	Description
`ADMIN_EMAIL`	Yes	Email for the initial admin account created during seeding
`ADMIN_USER`	Yes	Username for the initial admin account
`ADMIN_PASS`	Yes	Password for the initial admin account
`ASTRO_DB_REMOTE_URL`	For remote	Turso database URL
`ASTRO_DB_APP_TOKEN`	For remote	Turso access token
`ASTRO_DATABASE_FILE`	For local	Path to the local SQLite database file
`SITE`	Yes	Canonical site URL, used for SEO metadata and sitemap generation