> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lynxhub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Extension quick start

> Build and run a basic LynxHub extension in minutes.

LynxHub extensions allow you to customize the application shell, add custom React routes, register Redux state reducers, and interact with Node.js APIs in the main process.

Follow this guide to create and test a simple extension.

***

## Clone the starter template

To start developing quickly, first clone the host LynxHub application repository and navigate to its root folder. Then, clone the `source` branch of the official [LynxHub Extension Template](https://github.com/KindaBrazy/LynxHub-Extension-Template) directly into the `extension` folder:

```bash theme={null}
# Clone the host application
git clone https://github.com/KindaBrazy/LynxHub
cd LynxHub

# Clone the extension template source branch into the /extension directory
git clone -b source https://github.com/KindaBrazy/LynxHub-Extension-Template extension
```

This sets up the following folder structure:

```
extension/
├── electron.vite.config.ts  # Bundler and Module Federation configuration
├── package.json             # Identity and Node.js module configuration
└── src/
    ├── main/
    │   └── lynxExtension.ts # Main process background scripts
    └── renderer/
        └── Extension.tsx    # React component injected into host UI
```

***

## Define package configuration

Open the `package.json` file at the root of your `extension` folder and customize your extension's name, author information, and repository links.

```json theme={null}
{
  "name": "my-custom-extension",
  "version": "1.0.0",
  "author": {
    "name": "Your Name",
    "url": "https://github.com/your-username"
  },
  "homepage": "https://github.com/your-username/my-custom-extension",
  "repository": "https://github.com/your-username/my-custom-extension",
  "type": "module"
}
```

<Note>
  Extension metadata (`metadata.json`) and release version history (`versioning.json`) must be placed in a dedicated `metadata` branch of your repository. They are not
  stored in the `source` branch. For more details, see the [Extension configuration](/plugins/extensions/configuration) and [Publishing
  extensions](/plugins/extensions/publish) guides.
</Note>

***

## Implement the main process

Create a `src/main/lynxExtension.ts` file. This handles background processes, system-tray menus, and Electron lifecycle hooks.

```typescript theme={null}
import {ExtensionMainApi, MainExtensionUtils} from '@lynx_main/plugins/extensions/types';

export async function initialExtension(lynxApi: ExtensionMainApi, utils: MainExtensionUtils) {
  // Listen for the host application boot sequence
  lynxApi.onAppReady(async () => {
    console.log('Extension backend successfully initialized!');
  });
}
```

***

## Implement the renderer process

Create a `src/renderer/Extension.tsx` file. This injects UI elements, styles, and custom menus into the frontend.

```tsx theme={null}
import {ExtensionRendererApi} from '@lynx/plugins/extensions/types/api';

export function InitialExtensions(lynxAPI: ExtensionRendererApi) {
  // Inject a basic text widget into the end of the top title bar
  lynxAPI.titleBar.addEnd(() => <div className="px-3 py-1 text-xs font-semibold rounded-full bg-primary/20 text-primary">Hello from Extension!</div>);
}
```

***

## Run and test locally

Start the LynxHub host application in development mode:

```bash theme={null}
npm run dev
```

The application automatically detects the `/extension` directory and boots your custom code.

* Inspect your new Title Bar widget directly on the screen.
* Press `F12` or `Ctrl+Shift+I` to open the developer tools and verify the backend logs in your terminal.
* Run static validation and typecheck scripts to verify code health:
  ```bash theme={null}
  npm run validate:ext
  ```