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

# Contributing

> How to safely extend TS-Lib and its bridges.

TS-Lib powers multiple Thunder Scripts and centralizes all **framework / garage / vehicle keys / notify** integrations.\
Contributions are welcome, especially around new bridges, bug fixes and quality-of-life improvements.

***

## What kind of contributions make sense?

* **New bridges**
  * Support for another framework or a fork (`qbcore` fork, custom ESX build, etc.).
  * Support for another garage system.
  * Support for another keys system.
  * Support for another notification system.

* **Improvements to existing bridges**
  * More robust error handling and input validation.
  * Better logging when a dependency is missing or misconfigured.
  * Small performance or DB optimizations that don't change behavior.

* **Core utilities**
  * Additional, generic helpers that are clearly reusable across several scripts.
  * Documentation improvements and example code.

***

## Design principles

* **Single responsibility**
  * TS-Lib should stay small and focused. It is *not* a framework and it does *not* try to replace your existing utility libraries.

* **Bridges first**
  * Framework-specific logic should live inside:
    * `Bridge.Framework.*`
    * `Bridge.Garages.*`
    * `Bridge.VehicleKeys.*`
    * `Bridge.Notify.*`

* **Configuration driven**
  * New integrations should be made configurable via `ts-lib/config.lua`:
    * Add a new key in `Config.Data.Framework`, `Config.Data.Garages`, `Config.Data.VehicleKeys`, or `Config.Data.Notify`.
    * Do not hardcode resource names outside of this config.

* **Safe failure**
  * If a target resource is not started or misconfigured:
    * Log clearly with `TS.ErrorPrint`.
    * Fail gracefully instead of crashing other scripts.

***

## Adding a new bridge (high level)

1. **Extend the config**

   Edit `ts-lib/config.lua` and add your new option:

   ```lua theme={null}
   Config.Data.Garages['my-garage'] = 'my-garage-resource-name'
   ```

   Or for frameworks / keys / notify, use `Config.Data.Framework` / `Config.Data.VehicleKeys` / `Config.Data.Notify`.

2. **Create the bridge files**

   Follow the existing structure:

   * Frameworks: `shared/bridge/framework/<name>/shared.lua|client.lua|server.lua`
   * Garages: `shared/bridge/garages/<name>/shared.lua|client.lua|server.lua`
   * Keys: `shared/bridge/vehiclekeys/<name>/shared.lua|client.lua|server.lua`
   * Notify: `shared/bridge/notify/<name>/client.lua` (usually client-side only)

3. **Implement the required functions**

   * For a garage:
     * `Bridge.Garages.Server.Functions.IsVehicleOwned(plate, netId?)`
     * `Bridge.Garages.Server.Functions.SetVehicleOutsideState(plate, state)`

   * For vehicle keys:
     * `Bridge.VehicleKeys.Client.Functions.SetDoorStatus(entity, lockStatus)`

   * For notifications:
     * `Bridge.Notify.Client.Functions.Notify(message, type?)`

   * For frameworks:
     * See [Framework Bridge](/scripts/ts-lib/bridges-framework) for the expected surface.

4. **Guard against missing resources**

   * Use `TS.Utils.IsRessourceLoaded` (or FiveM native checks) before calling into other resources.
   * Log helpful messages if something is not started or misconfigured.

5. **Update the docs**

   * Add your bridge to the relevant "Supported systems" section.
   * Update the "Status & testing" table with its initial state (likely `Experimental`) and, if relevant, your nickname.

***

## Workflow for pull requests

1. **Fork** the TS-Lib repository on GitHub.
2. **Create a feature branch** with a clear name (for example `feat/my-garage-bridge` or `fix/esx-owner-query`).
3. Implement your changes:
   * Keep them focused and reasonably small.
   * Avoid unrelated refactors in the same PR.
4. **Test** on at least one real framework / garage / keys combination.
5. Open a **pull request**:
   * Describe the problem you're solving and the approach.
   * List the external resources involved (names + versions if possible).
   * Link to any relevant logs or screenshots.

If you're unsure whether an idea fits TS-Lib, you can start by opening a discussion or contacting support on [Discord](https://store.thunder-studio.net/discord).

***

## Reporting bugs & requesting features

* **Bugs**
  * Include:
    * OS (Windows / Linux), framework and main scripts used.
    * Exact console / F8 errors.
    * Steps to reproduce and, if possible, a small reproduction.

* **Feature requests**
  * Focus on the **use case** (for example, "I want to support X garage system") rather than a specific function name.
  * Often the best solution is a small, generic helper that works for several scripts.

You can report both via the [Discord](https://store.thunder-studio.net/discord).