Existing projects

Projects created with the gameface-ui template from create-gameface-app are already wired up and need nothing from this page.

Components already in your project?

If your project was created from the Gameface UI template before this CLI existed, its components are on disk but not recorded, so status and update cannot see them. Run npx gameface-cli track once to register them. It only writes to the package.json - your component files are left alone. See track.

Every other starting point needs a one-time setup, including the plain solid template. create-gameface-app scaffolds several frameworks, and only the Gameface UI template ships the aliases and style variables that components depend on.

The CLI prints a Setup required note the first time it installs into a project it doesn’t recognise. This page is what that note refers to.

Note

The CLI does not wire this up for you on purpose. tsconfig.json allows comments and vite.config is executable code, so neither can be edited automatically without risking your existing configuration.

Setup

1. Install sass

   Component stylesheets are written in SCSS. It is a build-time tool rather than a runtime dependency, so the CLI does not install it for you.

   npm

   npm install -D sass

   pnpm

   pnpm add -D sass

   yarn

   yarn add -D sass

2. Add the @components alias to tsconfig.json

   Components import each other through this alias, so TypeScript needs to resolve it:

   tsconfig.json

   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": {
         "@components/*": ["src/components/*"],
         "@assets/*": ["src/assets/*"]
       }
     }
   }

3. Add the same aliases to your Vite config

   TypeScript path mappings only affect type checking. Vite resolves imports at build time and needs to be told separately:

   vite.config.ts

   import { defineConfig } from 'vite';
   import solid from 'vite-plugin-solid';
   import path from 'node:path';
   
   export default defineConfig({
     plugins: [solid()],
     resolve: {
       alias: {
         '@components': path.resolve(__dirname, './src/components'),
         '@assets': path.resolve(__dirname, './src/assets'),
       },
     },
   });

4. Set up the style variables

   Every component stylesheet expects a set of shared SCSS variables to be available. Create the file at src/assets/scss/_variables.scss:

   src/assets/scss/_variables.scss

   // Your design tokens: colours, spacing, typography.
   // Component styles reference these, so the names must exist.
    $primaryColor: #868599;
    $secondaryColor: #3e3d5d;
    $disabledColor: #bdbdbd;
    $textColor: #ffffff;
    $disabledTextColor: #dddedf;

   Then inject it into every SCSS file so components don’t have to import it themselves:

   vite.config.ts

   export default defineConfig({
     // ...plugins and resolve as above
     css: {
       preprocessorOptions: {
         scss: {
           additionalData: `@use '@assets/scss/variables' as *;`,
         },
       },
     },
   });

Once that is in place, npx gameface-cli add <component> behaves exactly as it does in a Gameface UI project.

What a set-up project looks like

A plain Solid project after the setup above, with one component installed. Highlighted files are the ones you write or edit yourself.

• package.json the CLI records what it installed here, under gameface-ui-components
• tsconfig.json the @components and @assets paths from step 2
• vite.config.ts the matching aliases and the SCSS injection from steps 3 and 4
• Directorysrc

  • main.tsx
  • App.tsx
  • Directoryassets

    • Directoryscss

      • _variables.scss your design tokens, injected into every stylesheet
  • Directorycomponents your components and the CLI’s, side by side

    • DirectoryBaseComponent

      • BaseComponent.tsx
    • DirectoryBasic

      • DirectoryButton

        • Button.tsx
        • Button.module.scss
    • DirectoryUtility

      • DirectoryNavigation

        • Navigation.tsx
        • …
    • Directorytypes

      • ComponentProps.d.ts
      • …
    • Directoryutils

      • waitForFrames.ts
      • …
    • DirectoryHUD yours, and the CLI will never touch it

      • HUD.tsx
      • HUD.module.scss

Only Button was asked for. BaseComponent, Utility/Navigation, types and utils came along as its dependencies, which is why the folder looks fuller than a single install suggests. Those shared folders are reused by every component, so the next few installs add much less.

Living alongside your own components

There is no separate folder to keep your components in. Put them wherever you like, src/components/ included - the CLI has no opinion about what else is in there.

What it does have is a fixed list of paths it owns. On every add and update it writes those paths from the registry, overwriting whatever is there without merging and without asking. Inside src/components/, that list is:

BaseComponent/  Basic/  Complex/  Feedback/  Layout/  Media/  Utility/  types/  utils/

Path collisions

The one rule is not to put your own files at a path the CLI already claims. src/components/Basic/Button/Button.tsx belongs to Gameface UI, and a Button of your own written there disappears the first time anyone installs or updates the Gameface UI one. Naming your component Button is fine. Path like src/components/HUD/Button.tsx is safe if adding the Button component. It is only the collision of the full path that costs you the file.

Components that need a full Gameface project

Icon and Keybinds are not available outside a Gameface UI project. They depend on generated type files, an icon-generation script, and gamepad glyph assets that only exist in the full template, so installing them here would leave you with components that don’t build.

If you need them, start from create-gameface-app with the gameface-ui template instead.

Troubleshooting

Problem	Fix
Cannot find module '@components/...'	The alias is missing from tsconfig.json, from your Vite config, or from both. Each needs its own copy: TypeScript uses it for type checking, Vite for resolving the actual import.
Undefined variable errors from SCSS	Either _variables.scss does not exist, additionalData is not injecting it, or the variable names do not match. Component styles reference specific names such as $primaryColor, $secondaryColor and $textColor, so your own tokens have to use those names rather than equivalents of your own choosing.
npm installation failed	The component files were written, but installing their npm dependencies did not work. The CLI prints the exact command to run by hand. A pre-existing unresolvable dependency in your package.json is the usual cause, since npm resolves the whole tree on any install.
Gameface UI components require a SolidJS project	solid-js is not in your package.json. Install it, or start from the gameface-ui template.
status shows almost nothing installed, but the components are clearly there	They were never recorded under gameface-ui-components. Run npx gameface-cli track to register what is already on disk.
track reports a component as behind that you never touched	Its files differ from the published version, which usually means they are simply from an older release. Run with --verbose to see exactly which files differ.
Styles are missing after an update	The update replaced a stock component you had edited in place. Re-apply the change as a wrapper or through props so it lives at a path of your own, then re-run the update.
A file of your own disappeared after add or update	It was at a path the registry owns. Recover it from source control and move it out of BaseComponent/, Basic/, Complex/, Feedback/, Layout/, Media/, Utility/, types/ and utils/ - anywhere else under src/components/ is safe.