How to use

GamefaceUI offers two primary ways to get started, depending on whether you want to create a new project from scratch or integrate its components into an existing SolidJS project. You can:

• Download a complete boilerplate template that uses SolidJS with TypeScript and Vite.
• Integrate the components into an existing SolidJS project.

Using the Boilerplate

The boilerplate is ideal for starting a new project. It comes pre-configured with tools and features to streamline game UI development:

• Vite build tool for efficient development and production builds.
• Vite plugins for an enhanced development experience.
• A structured template to guide your UI implementation. Details about the structure can be found here.
• TypeScript for type checking and error prevention.
• Pre-built components for faster UI development.

Caution

If you choose not to use the boilerplate and only the components, we highly recommend reviewing the boilerplate here to familiarize yourself with its structure, tools, and usage.

To get started with the boilerplate, navigate to your desired directory and run:

npm create gameface-app -- -t gameface-ui -d

This command runs an installation wizard that asks you to name your project, then downloads the boilerplate and installs its dependencies.

After the installation is complete, navigate to the newly created project folder and run:

cd your-project-name
npm run dev

You can then proceed with building and developing your UI.

Using Components Only

Note

To use the components independently, you must have a SolidJS project set up with TypeScript, as GamefaceUI components are written in .tsx syntax.

Rather than downloading every component, use the Gameface CLI to add only the ones you need. Run it from the root of your project:

npx gameface-cli add Dropdown

The CLI does more than copy a file across. For each component you add, it will:

• Create the folders it needs and write the component’s files into them.
• Pull in everything that component depends on (other components, shared utilities, base types) so it works the moment it lands.
• Install any npm packages the component requires.
• Record what it installed, and at which version, in your package.json under gameface-ui-components. That record is what makes updating possible later.

To browse everything available, and see what you already have:

npx gameface-cli list

Adding components to your own project

If you are adding components to an existing SolidJS project rather than the boilerplate, the CLI installs them and then prints a short setup checklist covering:

• the @components path alias, in both your tsconfig and your Vite config
• the @assets/scss/variables import that the component stylesheets rely on
• installing sass, which compiles those stylesheets

These are one-time steps, and the CLI deliberately does not edit those files for you. Your build configuration stays yours. The CLI documentation covers setting up an existing project in full.

Caution

The Icon and Keybinds components depend on the boilerplate’s asset pipeline, so they cannot be added to a plain SolidJS project.