Development Mode
================

During development, you don't need to build a ``.forkbit`` archive every
time you change your plugin. ForkBit can load plugins directly from a
local directory — even in the released DMG version.

Setting up dev mode
-------------------

1. Open ForkBit and go to **Settings → Plugins**
2. Scroll down to the **Development** section
3. Click **"Add Path…"** and select your plugin directory
   (the folder containing ``plugin.json``)
4. ForkBit validates that the directory has a valid manifest

Your plugin now appears in the **Add Plugin** dialog with a ``(dev)``
label next to its name. Add it to any project like a normal plugin.

.. note::

   Changes to your plugin code take effect after restarting the plugin
   or the app. There is no hot-reload — you need to restart to pick up
   code changes.

Recommended project setup
-------------------------

Create a dedicated directory with its own virtual environment:

.. code-block:: bash

   mkdir my-plugin && cd my-plugin
   python3 -m venv .venv
   source .venv/bin/activate
   pip install forkbit-sdk

Scaffold the plugin:

.. code-block:: bash

   forkbit plugin init --id com.mycompany.myplugin --name "My Plugin" --non-interactive .

Your directory should look like this:

.. code-block:: text

   my-plugin/
     .venv/              — virtual environment with forkbit-sdk
     plugin.json         — manifest
     main.py             — your plugin code
     settings.json       — settings schema

Now register the path in ForkBit (Settings → Plugins → Development →
Add Path), and you can iterate without building.

Multiple files
--------------

Plugins can have multiple Python files. The entry point in ``plugin.json``
is the file that contains your ``BasePlugin`` subclass, but you can
import from sibling modules freely:

.. code-block:: text

   my-plugin/
     plugin.json
     main.py             — entry point (BasePlugin subclass)
     workers.py           — background threads
     widgets.py           — custom widgets

.. code-block:: python

   # main.py
   from workers import MyWorker
   from widgets import MyCard

These imports work because the plugin directory is added to ``sys.path``
at load time.

Accessing app internals
-----------------------

Dev plugins run in-process and can import from the app's modules:

.. code-block:: python

   # Access the app's theme system
   from ui.theme import icon, ToggleSwitch, XL, L, S

   # Access the app's shared widget kits
   from core.translation_kit import TranslatableField, LocalePicker
   from core.price_kit import CurrencyInput, PriceTable

These imports are available because the app adds its own root to
``sys.path``. They work in both dev mode and when the plugin is
built as a ``.forkbit`` file.

.. warning::

   Imports from ``ui.*`` and ``core.*`` are app internals and may change
   between ForkBit versions. Only ``forkbit_sdk`` is a stable public API.

When to build
-------------

Use dev mode for development and testing. Build a ``.forkbit`` file when
you're ready to distribute:

.. code-block:: bash

   forkbit plugin validate .
   forkbit plugin build .          # current platform only
   forkbit plugin release .        # all platforms

See :doc:`build` for details on building and distributing.