Ergogen GUI

Welcome to the Ergogen GUI, a powerful web-based interface for the Ergogen keyboard generation tool by @MrZealot. This project, originally created by @MvEerd and enhanced by @ceoloide and the community, provides a user-friendly environment to design, preview, and export custom ergonomic keyboards.

With this GUI, you can write Ergogen configurations in YAML, see live 2D (SVG) previews of your design, and export the necessary files for manufacturing your own keyboard.

See the live demo at ergogen.xyz.

Features

• Live 2D Previews: Instantly see your changes reflected in 2D (SVG) previews as you type.
• PCB Preview: Visualize your generated PCBs directly in the browser using an integrated KiCanvas viewer.
• Integrated Monaco Editor: Enjoy a rich, VSCode-like editing experience for your YAML configurations with syntax highlighting.
• Real-time Output Generation: Automatically regenerates outlines, 3D models, and PCB files.
• File Downloads: Easily download generated files, including DXF for outlines, JSCAD for 3D models, and KiCad files for PCBs.
• Custom Footprints: Bundles custom footprints from ceoloide/ergogen-footprints and allows for custom user-defined footprints. (Note: Custom template injection is not yet supported).
• Example Loader: Load example configurations directly from GitHub URLs or choose from a list of built-in examples to get started quickly.
• Adjustable Settings: Fine-tune the generation process with options to toggle auto-generation, debug mode, and experimental preview features.

Getting Started

To run the Ergogen GUI on your local machine, please follow these steps.

Prerequisites

• Node.js: You must have Node.js v20 or newer installed (e.g., Node.js v24). We recommend using a version manager like nvm to easily switch between Node versions.
  • nvm install 24
  • nvm use 24
• pnpm: This project uses pnpm for package management.
  • npm install -g pnpm

Installation and Setup

1. Clone the repository:

   git clone https://github.com/ceoloide/ergogen-gui.git
   cd ergogen-gui

2. Install dependencies:

    pnpm install

   This command will also build a local copy of Ergogen from the patched source in the patch/ directory.

3. Start the development server:

    pnpm run dev

   This will start a development server and open the application in your default browser at http://localhost:3000.

How to Use

The Ergogen GUI is divided into three main sections: the configuration editor on the left, the file preview in the middle, and the downloads/outputs list on the right.

• Configuration Editor: Write or paste your Ergogen YAML configuration here. The previews will update automatically as you type (if auto-generation is enabled).
• File Preview: This panel shows a preview of the selected output file. You can switch between different outputs, like outlines (SVG) or PCBs (via KiCanvas), by clicking the "Preview" button next to the file name in the "Outputs" list.
• Outputs: This section lists all the files generated from your configuration. You can download any file by clicking the download icon next to it.
• Settings: Click the gear icon in the header to open the settings panel. Here, you can manage custom footprints and adjust generation options.

Creating Share Links (For External Developers)

If you're building a tool that generates Ergogen configurations, you can create share links that open the Ergogen GUI with your configuration preloaded. This allows your users to instantly preview and edit the generated config.

Share Link Format

Share links use URL hash fragments: https://ergogen.xyz/#<encoded-data>

The encoded data is a JSON object compressed using lz-string:

interface ShareableConfig {
  config: string; // The YAML or JSON configuration (required)
  injections?: string[][]; // Optional custom injections (footprints, templates, outlines): [type, name, code][]
  guiVersion?: string; // Optional GUI version compatibility check
  ergogenVersion?: string; // Optional Ergogen version compatibility check
}

Basic Example (JavaScript)

import { compressToEncodedURIComponent } from 'lz-string';

function createErgogenShareLink(yamlConfig) {
  const shareableConfig = {
    config: yamlConfig,
  };

  const encoded = compressToEncodedURIComponent(
    JSON.stringify(shareableConfig)
  );
  return `https://ergogen.xyz/#${encoded}`;
}

// Usage
const config = `
points:
  zones:
    matrix:
      columns:
        pinky:
        ring:
        middle:
        index:
      rows:
        bottom:
        home:
        top:
`;

const shareLink = createErgogenShareLink(config);
console.log(shareLink);

Including Custom Injections (Footprints, Templates, Outlines)

If your configuration uses custom footprints, templates, or outlines, include them in the injections array. Each injection is a tuple of [type, name, code], where type can be 'footprint', 'template', or 'outline':

import { compressToEncodedURIComponent } from 'lz-string';

function createErgogenShareLink(yamlConfig, injections = []) {
  const shareableConfig = {
    config: yamlConfig,
  };

  // Add custom injections if provided
  if (injections.length > 0) {
    shareableConfig.injections = injections.map((inj) => [
      inj.type, // 'footprint', 'template', or 'outline'
      inj.name, // e.g., 'my_custom_switch'
      inj.code, // JavaScript footprint code, template code, or outline SVG
    ]);
  }

  const encoded = compressToEncodedURIComponent(
    JSON.stringify(shareableConfig)
  );
  return `https://ergogen.xyz/#${encoded}`;
}

// Usage with custom footprint injection
const config = `
points:
  zones:
    matrix:
      columns:
        pinky:
      rows:
        home:
pcbs:
  main:
    footprints:
      switch:
        what: my_custom_footprint
        where: true
`;

const footprints = [
  {
    type: 'footprint',
    name: 'my_custom_footprint',
    code: `
module.exports = {
  params: {
    designator: '',
  },
  body: p => \`\`
}
  `,
  },
];

const shareLink = createErgogenShareLink(config, footprints);

Notes

• The configuration can be either YAML or KLE (Keyboard Layout Editor) JSON format
• Share links work with any Ergogen GUI deployment (not just ergogen.xyz)
• Very large configurations may create long URLs; consider URL length limits (~2000-8000 chars depending on browser)
• When users open a share link, the configuration is loaded and Ergogen immediately processes it

Deployment to GitHub Pages

This repository includes a GitHub Actions workflow to automatically build and deploy the application to GitHub Pages whenever changes are pushed to the main branch.

Dynamic Deployment URL

The deployment workflow is designed to be flexible for forks and custom domains. It uses a repository variable to set the correct PUBLIC_URL during the build process. This ensures that all asset paths are generated correctly for the environment where the application will be hosted.

To configure the deployment URL for your repository:

1. Go to your repository on GitHub.
2. Navigate to Settings > Secrets and variables > Actions.
3. Select the Variables tab and click New repository variable.
4. For the Name, enter PUBLIC_URL.
5. For the Value, enter the relative path where the application will be hosted. For example:
   • For a custom domain: https://ergogen.xyz enter /
   • For a standard GitHub Pages site: https://<username>.github.io/<repository-name> enter /<repository-name>
6. Click New repository variable again.
7. For the Name, enter REACT_APP_GTAG_ID.
8. For the Value, enter your Google Tag ID to capture Google Analytics for the site.

If the PUBLIC_URL variable is not set, the workflow will automatically use / as the default value.

Troubleshooting GitHub Pages

If you are having issues deploying after forking this repository, try renaming the deploy.yaml workflow configuration to any other name. This should prompt GitHub to load the new configuration and get unstuck.

Project Structure

The codebase is organized into the following main directories:

• index.html: The main entry point file.
• public/: Contains static assets, including the Ergogen and KiCanvas libraries.
• src/: Contains the main React application source code.
  • atoms/: Individual, reusable UI components (e.g., Button, Input).
  • molecules/: More complex components composed of atoms (e.g., ConfigEditor, FilePreview).
  • organisms/: Large UI sections composed of molecules and atoms (e.g., Tabs).
  • context/: React context providers, primarily for managing the global configuration state (ConfigContext).
  • examples/: Contains built-in example configurations.
  • utils/: Utility functions, such as for fetching data from GitHub.
• patch/: Contains scripts and patches for customizing the ergogen dependency.

Using a Custom Ergogen Version or Branch

By default, the GUI uses the Ergogen version specified in package.json. You can override this at build or deploy time using the ERGOGEN_VERSION environment variable. This is useful for testing specific versions, branches, or forks without modifying the source code. The active version will be displayed in the application header and side navigation.

Local Development

To use a custom version locally, set the ERGOGEN_VERSION variable before running the install or build commands:

# Using a specific npm version
ERGOGEN_VERSION=ergogen@4.2.0 pnpm install

# Using a GitHub branch
ERGOGEN_VERSION=github:mrzealot/ergogen#develop pnpm install

# After installation, start as usual
pnpm run dev

GitHub Pages Deployment

To use a custom Ergogen version for your GitHub Pages deployment:

1. Go to your repository on GitHub.
2. Navigate to Settings > Secrets and variables > Actions.
3. Select the Variables tab and click New repository variable.
4. For the Name, enter ERGOGEN_VERSION.
5. For the Value, enter your desired version (e.g., ergogen@4.2.0 or github:username/ergogen#branch).
6. Re-run your deployment workflow.

The deployment workflow will automatically pick up this variable and use it during the build process.

Manual Override in package.json

Alternatively, you can still manually modify package.json:

1. Open package.json.

2. Update the ergogen dependency:

   "ergogen": "ergogen/ergogen#develop",

3. Run pnpm install && pnpm run dev.

Contributing

Contributions are welcome! If you have a feature request, bug report, or want to contribute to the code, please feel free to open an issue or submit a pull request.

License

This project is licensed under the MIT License.