=====
Usage
=====

The usage documentation is for end users of the library. It provides a high-level
overview of what features are available and how to use them.

Core Features
-------------

.. toctree::
    :titlesonly:
    :maxdepth: 2

    inertia
    vite

Getting Started
---------------

1. Installation
~~~~~~~~~~~~~~~

Install litestar-vite using your preferred package manager:

.. code-block:: bash

    pip install litestar-vite

**Note:** If you do not have an existing node environment, you can use `nodeenv` to automatically configure one for you by using the ``litestar-vite[nodeenv]`` extras option.

2. Basic Configuration
~~~~~~~~~~~~~~~~~~~~~~~

The plugin executes in one of two modes:

- Hot Reloading: The plugin will start a Vite dev server and serve assets from it.  When developing, this is the typical setting you would use.  When using this, Vite is started using the port from the ``dev_server_port`` option.  A websocket connection is established to the dev server from the Jinja templates to enable hot reloading.
- Production Mode: The plugin will bundle assets and serve them from the specified bundle directory.  When this mode is active, assets are served from the ``bundle_dir`` option.  You must ensure that there is a `manifest.json` file in the ``bundle_dir`` directory.  This file is generated by Vite when you build the runtime assets.

Configure your Litestar application with the Vite plugin:

.. code-block:: python

    from litestar import Litestar
    from litestar_vite import ViteConfig, VitePlugin

    app = Litestar(
        plugins=[
            VitePlugin(
                config=ViteConfig(
                    bundle_dir="public",
                    resource_dir="resources",
                    use_server_lifespan=True,
                    hot_reload=True
                )
            )
        ]
    )

3. Bootstrap the Typescript Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you do have an existing vite application, you can create a new one for your Litestar application with the following command:

.. code-block:: bash

    litestar assets init
    litestar assets install

For more detailed information about specific features, refer to the sections in the sidebar.



.. toctree::
    :titlesonly:
    :glob:

    *