Metadata-Version: 2.3
Name: canonicalwebteam.flask-vite
Version: 0.1.0
Summary: A Flask extension that integrates with Vite
License: LGPL-3.0
Author: Canonical Web Team
Author-email: webteam@canonical.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: flask (>=2.3,<3.0)
Project-URL: Homepage, https://github.com/canonical/canonicalwebteam.flask-vite
Project-URL: Issues, https://github.com/canonical/canonicalwebteam.flask-vite/issues
Description-Content-Type: text/markdown

# Canonical Webteam Flask-Vite integration

A Flask extension that integrates with Vite, enabling use of Vite's dev server and static builds with as little configuration as possible.

## Features
- easy to configure
- simple API
- supports custom Vite configurations
- supports multiple JS entry points
- supports all Vite-compatible JS frameworks
- supports all Vite-compatible stylesheet languages
- hot reloading in development mode
- `modulepreload` hints for JS chunks in production mode


## How to use the extension

### Install
To install this extension as a requirement in your project, you can use PIP:
```bash
pip install canonicalwebteam.flask-vite
```

### Configure
The extension parses the following values from the Flask `app.config` object:
  - `VITE_MODE: "development" | "production"` - type of environment in which the Vite integration will run
  - `VITE_PORT: int` - port where Vite's dev server is running
  - `VITE_OUTDIR: str` - file system path where the Vite output is expected; the path can be absolute or relative to the Flask app's root directory

### Import
The extension adds a new template global function named `vite_import`. To include a script or stylesheet, simply invoke this template function passing the path to the file you want to import, relative to the app's root directory.

#### Example
To import a script whose path is `< flask app directory >/js/app/main.ts`:
```html
{ vite_import("js/app/main.ts") }
```

> Note: all files imported via `vite_import` must be declared as entry points in your Vite config; if this isn't the case, the Vite build command will not process the file you're trying to import, so the extension will NOT work in production mode.


## Minimal usage example

```python
# app.py
app = Flask()

app.config["VITE_MODE"] = "development" if app.debug else "production"
app.config["VITE_PORT"] = 9999
app.config["VITE_OUTDIR"] = "static/dist"

vite = FlaskVite()
vite.init_app(app)

# ...
```

```html
<!-- templates/base.html -->
<head>
  { vite_import("path/to/source/styles.scss") }
</head>
<body>
  <!-- ... -->
  { vite_import("path/to/source/file.tsx") }
</body>
```

## Development

The package leverages [poetry](https://poetry.eustace.io/) for dependency management.

To set up the virtual env and install dependencies, run:
```bash
poetry install
```

## Testing

Unit tests can be run using:
```bash
poetry run python3 -m unittest discover tests
```

