UI Configuration

Customize Guccho’s appearance, branding, footer links, and leaderboard display settings

The UI configuration file (guccho.ui.config.ts) controls the visual appearance and branding of your Guccho frontend.

Creating Your Configuration

Copy the example configuration file and customize it:

cp guccho.ui.config.example.ts guccho.ui.config.ts

Use an editor with TypeScript support for better error detection and autocomplete.

Configuration Structure

Your configuration file should export a default object that satisfies the UIConfig type:

import { type UIConfig } from './src/def/config.d'
import { Lang, Rank } from './src/def'

export default {
  // your configuration
} satisfies UIConfig

Server Identity

baseUrl · string · required

Base domain of your server. Use the root domain without subdomains.

Example: If your server is at c.ppy.sh, use ppy.sh

baseUrl: 'dev.ppy.sb'

legacyOption.name · string

The name of your server. This is a simple way to set your server name.

legacyOption: {
  name: 'Guccho',
}

For more advanced localization, use the i18n configuration to provide different names in multiple languages.

Branding

brand · object

Configure the branding icon displayed in the top and bottom left corners.

brand: {
  icon: 'ion:paw',
  iconClass: 'w-8 h-4',
}

Show Brand Fields

brand.icon · string

Icon identifier. Guccho uses Iconify for icons, so you can use any icon from the Iconify icon sets.

Format: collection:icon-name

Examples:

• ion:paw - Paw icon from Ionicons
• mdi:music - Music icon from Material Design Icons
• fa:heart - Heart icon from Font Awesome

icon: 'ion:paw'

brand.iconClass · string | string[] | Record<string, string>

CSS classes to apply to the icon for sizing and styling.

iconClass: 'w-8 h-4'  // Tailwind classes

Browse Iconify to find the perfect icon for your server’s brand.

Footer Links

iconLinks · IconLink[]

Small icon links displayed in the footer.

iconLinks: [
  {
    icon: 'tabler:brand-nuxt',
    link: 'https://nuxt.com',
    name: 'nuxt'
  }
]

Show IconLink Fields

icon · string · required

Iconify icon identifier.

link · string · required

URL to link to.

name · string

Internal name for the link.

footerLink · object

Organized footer links grouped by category.

Guccho provides predefined keys with built-in translations:

• about - Links related to your server
• resources - External resources and tools

footerLink: {
  about: [
    {
      localeKey: 'footer.blog',
      link: 'https://blog.ppy.sb',
    }
  ],
  resources: [
    {
      localeKey: 'footer.nuxt',
      link: 'https://nuxt.com',
    }
  ],
}

Show Adding Custom Sections

You can add custom footer sections beyond about and resources:

footerLink: {
  // Custom section
  store: [
    {
      localeKey: 'footer.my-store',
      link: 'https://store.example.com',
    }
  ],
},
i18n: {
  messages: {
    [Lang.enGB]: {
      footer: {
        store: 'Store',  // Section title
        'my-store': 'My Store',  // Link text
      },
    },
  },
}

Custom sections require you to provide translations in the i18n configuration.

Internationalization (i18n)

i18n.messages · Partial<Record<Lang, Record<string, any>>>

Locale translations for customizing text in different languages.

i18n: {
  messages: {
    [Lang.enGB]: {
      footer: {
        blog: 'Blog',
        nuxt: 'Nuxt',
      },
    },
  },
}

Show Multi-Language Server Names

Provide different server names for each language:

i18n: {
  messages: {
    [Lang.enGB]: {
      server: {
        name: 'ppy.sb',
      },
    },
    [Lang.frFr]: {
      server: {
        name: 'ppŷ.śb',
      },
    },
    [Lang.zhCN]: {
      server: {
        name: '偏偏要上班',
      },
    },
  },
}

Supported languages are defined in ./src/def. Contact the Guccho team if you want to contribute translations for additional languages.

Leaderboard Ranking Systems

leaderboardRankingSystem · Record<LeaderboardRankingSystem, RankConf> · required

Configure how different ranking systems are displayed on user pages.

leaderboardRankingSystem: {
  [Rank.PPv2]: {
    userpage: {
      show: 'tab',
    },
  },
  [Rank.PPv1]: {
    userpage: {
      show: 'dropdown',
    },
  },
  [Rank.RankedScore]: {
    userpage: {
      show: 'tab',
    },
  },
  [Rank.TotalScore]: {
    userpage: {
      show: 'tab',
    },
  },
}

Show Display Options

userpage.show · 'tab' | 'dropdown'

How to display this ranking system on user pages.

Options:

• tab - Show as a prominent tab (for primary ranking systems)
• dropdown - Show in a dropdown menu (for secondary ranking systems)

[Rank.PPv2]: {
  userpage: {
    show: 'tab',  // Primary ranking system
  },
},
[Rank.PPv1]: {
  userpage: {
    show: 'dropdown',  // Secondary ranking system
  },
}

Use tab for your primary ranking systems (like PPv2 and Ranked Score) and dropdown for alternative or legacy ranking systems.

Complete Example

import { type UIConfig } from './src/def/config.d'
import { Lang, Rank } from './src/def'

export default {
  // Server identity
  legacyOption: {
    name: 'Guccho',
  },
  baseUrl: 'dev.ppy.sb',

  // Branding
  brand: {
    icon: 'ion:paw',
    iconClass: 'w-8 h-4',
  },

  // Footer icon links
  iconLinks: [
    {
      icon: 'tabler:brand-nuxt',
      link: 'https://nuxt.com',
      name: 'nuxt'
    }
  ],

  // Footer link sections
  footerLink: {
    about: [
      {
        localeKey: 'footer.blog',
        link: 'https://blog.ppy.sb',
      }
    ],
    resources: [
      {
        localeKey: 'footer.nuxt',
        link: 'https://nuxt.com',
      }
    ],
  },

  // Internationalization
  i18n: {
    messages: {
      [Lang.enGB]: {
        footer: {
          blog: 'Blog',
          nuxt: 'Nuxt',
        },
      },
    },
  },

  // Leaderboard ranking systems
  leaderboardRankingSystem: {
    [Rank.PPv2]: {
      userpage: {
        show: 'tab',
      },
    },
    [Rank.PPv1]: {
      userpage: {
        show: 'dropdown',
      },
    },
    [Rank.RankedScore]: {
      userpage: {
        show: 'tab',
      },
    },
    [Rank.TotalScore]: {
      userpage: {
        show: 'tab',
      },
    },
  },
} satisfies UIConfig

Next Steps

Backend Configuration

Configure database, Redis, and backend adapters

Environment Variables

Manage environment variables and secrets