Plugins
Beta API Notice: The plugin system is in beta, and its API may change between versions.
Package a feature as a plugin when you need it in more than one Mountaineer app. A plugin can include its own controllers, views, models, and assets.
Plugins can package:
- Controllers - Backend logic and API endpoints
- Views - Frontend React components and pages
- Models - Data structures and database schemas
- Static assets - CSS, images, and other resources
- Build configuration - Custom bundlers and compilation steps
Build a plugin's frontend assets before distributing it, so host applications can serve those assets when they register the plugin.
First-Party Plugins
We maintain three open source plugins:
| Plugin | What you get |
|---|---|
| Auth | Email/password auth, sessions, password reset, admin users |
| Billing | Stripe subscriptions, metered usage, webhooks, checkout |
| Cloud | File storage and email across AWS, Cloudflare, DigitalOcean, and Resend |
These plugins use config mixins, model mixins, and Depends for dependency injection. You can combine them; for example, one User table can carry both auth and billing fields:
from iceaxe import TableBase
from mountaineer_auth.models import UserAuthMixin
from mountaineer_billing.models import UserBillingMixin
class User(UserBillingMixin, UserAuthMixin, TableBase):
pass
Motivating Examples
Plugins are useful when a feature needs both backend logic and a reusable interface. For example:
1. Development Tools & Debugging
An exception viewer can package stack-trace processing with a page for inspecting the result, as mountaineer-exceptions does.
2. Authentication & Security
A login plugin can share session handling, user models, and login views across apps.
3. Content Management
A blog plugin can combine post storage with editing and publishing pages.
4. E-commerce & Payments
A checkout plugin can bundle payment routes, webhook handling, and purchase views.
5. Communication & Notifications
A messaging plugin can provide delivery logic alongside templates or an inbox UI.
Plugin Structure
mountaineer-exceptions keeps its Python code and frontend assets in one package:
mountaineer-exceptions/
├── pyproject.toml # Package configuration
├── mountaineer_exceptions/
│ ├── __init__.py
│ ├── plugin.py # Main plugin definition
│ ├── cli.py # Build script for the plugin
│ ├── controllers/ # Backend controllers
│ │ ├── __init__.py
│ │ ├── exception_controller.py # Main controller logic
│ │ └── traceback.py # Supporting utilities
│ └── views/ # Frontend views
│ ├── __init__.py # View path utilities
│ ├── core/
│ │ ├── main.css # Plugin-specific styles
│ │ ├── layout.tsx # Layout components
│ │ └── exception/
│ │ ├── page.tsx # Main exception page
│ │ └── _server/ # Generated server hooks
│ └── _static/ # Compiled assets
└── README.md
Core Plugin Conventions
1. Plugin Definition File
Every plugin must have a plugin.py file that defines a MountaineerPlugin instance:
from fastapi import APIRouter
from mountaineer.client_compiler.postcss import PostCSSBundler
from mountaineer.plugin import BuildConfig, MountaineerPlugin
from your_plugin.controllers.main_controller import MainController
from your_plugin.views import get_core_view_path
router = APIRouter()
@router.get("/your-plugin/api/health")
def healthcheck():
return {"status": "ok"}
plugin = MountaineerPlugin(
name="your-plugin-name",
controllers=[MainController],
view_root=get_core_view_path(""),
build_config=BuildConfig(custom_builders=[PostCSSBundler()]),
router=router,
)
Required fields:
name: Unique identifier for your plugin
Optional fields:
controllers: List of controller classes to registerview_root: Path to the plugin's view directory. Required when plugin controllers use relativeview_pathvalues. If every controller already uses aManagedViewPathunder one shared root, Mountaineer can infer it.build_config: Custom build configuration with bundlers, CSS processors, etc.router: Optional FastAPIAPIRouterfor plugin-owned API endpoints that are not tied to a controller action
Plugins can be view-backed, router-only, or a mix of both. If your plugin only exposes a FastAPI router, you can omit both controllers and view_root.
2. View Path Management
Plugins should provide a utility function for resolving view paths:
from importlib.resources import as_file, files
from pathlib import Path
def get_core_view_path(asset_name: str) -> Path:
with as_file(files(__name__).joinpath(asset_name)) as path:
return Path(path)
Resolve views relative to the installed package rather than the application's working directory.
3. Controller Structure
Plugin controllers follow standard Mountaineer controller conventions:
from mountaineer.controller import ControllerBase
from mountaineer.paths import ManagedViewPath
from mountaineer.render import RenderBase
from your_plugin.views import get_core_view_path
class MainRender(RenderBase):
# Define your render data structure
message: str
items: list[dict]
class MainController(ControllerBase):
url = "/your-plugin" # Plugin routes should be namespaced
view_path = (
ManagedViewPath.from_view_root(get_core_view_path(""))
/ "core/main/page.tsx"
)
def render(self) -> MainRender:
return MainRender(
message="Hello from plugin!",
items=[{"id": 1, "name": "Example"}]
)
4. Frontend Views
Plugin views are standard React components with TypeScript:
import React from "react";
import { useServer } from "./_server/useServer";
const MainPage = (): JSX.Element => {
const serverState = useServer();
return (
<div className="p-8">
<h1 className="text-2xl font-bold">{serverState.message}</h1>
<ul className="mt-4">
{serverState.items.map((item) => (
<li key={item.id} className="py-2">
{item.name}
</li>
))}
</ul>
</div>
);
};
export default MainPage;
5. Build Configuration
Plugins should include a CLI build script for compilation:
from mountaineer.cli import handle_build
from your_plugin.plugin import plugin
app = plugin.to_webserver()
def build() -> None:
handle_build(webcontroller="your_plugin.cli:app")
And register it in pyproject.toml:
[project.scripts]
build-your-plugin = "your_plugin.cli:build"
6. Package Configuration
Your pyproject.toml should include build artifacts:
[tool.hatch.build]
artifacts = ["your_plugin/views/_static", "your_plugin/views/_ssr"]
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
Creating a Plugin
1. Project Setup
mkdir my-awesome-plugin
cd my-awesome-plugin
# Initialize with uv
uv init
uv add mountaineer
2. Create Plugin Structure
mkdir -p my_awesome_plugin/{controllers,views/core/main}
touch my_awesome_plugin/__init__.py
touch my_awesome_plugin/plugin.py
touch my_awesome_plugin/cli.py
touch my_awesome_plugin/controllers/__init__.py
touch my_awesome_plugin/views/__init__.py
3. Implement Your Plugin
Follow the conventions outlined above to implement your controllers, views, and plugin definition.
4. Build Your Plugin
# Build the frontend assets
uv run build-my-awesome-plugin
# Package for distribution
uv build
Using a Plugin
1. Install the Plugin
# From PyPI (if published)
uv add my-awesome-plugin
# From local development
uv add --editable ../my-awesome-plugin
# From Git repository
uv add git+https://github.com/user/my-awesome-plugin.git
2. Register in Your App
from mountaineer.app import AppController
from my_awesome_plugin.plugin import plugin
controller = AppController(config=AppConfig())
# Mount the plugin (this registers all controllers automatically)
controller.register(plugin)
Use controller.register(plugin) instead of manually looping over plugin.controllers. This ensures plugin routers, static assets, and controller initialization all get wired up consistently.
3. Include Plugin Assets
If your plugin includes CSS or other static assets, make sure to include them in your app's metadata:
from mountaineer.render import LinkAttribute, Metadata
controller = AppController(
config=AppConfig(),
global_metadata=Metadata(
links=[
LinkAttribute(rel="stylesheet", href="/static/app_main.css"),
LinkAttribute(
rel="stylesheet",
href="/static_plugins/my-awesome-plugin/plugin_main.css",
),
]
),
)
If your plugin ships compiled frontend assets, they are mounted under /static_plugins/{plugin.name} rather than the host app's /static namespace.
Best Practices
Namespace Your Routes
Use descriptive URL prefixes to avoid conflicts:
class PluginController(ControllerBase):
url = "/my-plugin/dashboard" # Good: namespaced
# url = "/dashboard" # Bad: could conflict
Encapsulate Dependencies
Include all necessary dependencies in your plugin's pyproject.toml:
dependencies = [
"mountaineer>=0.1.0",
"pygments>=2.19.1", # Plugin-specific dependencies
]
Provide Clear Documentation
Include a README with:
- Installation instructions
- Configuration options
- Usage examples
- Screenshots or demos
Version Compatibility
Test your plugin against multiple Mountaineer versions and document compatibility:
dependencies = [
"mountaineer>=0.1.0,<1.0.0", # Specify version range
]
If your plugin depends on specific integration behavior, be explicit about that in your README as well. For example, note whether it works as a router-only plugin, whether it requires compiled view assets, and whether its controllers use relative view_path values or inferred ManagedViewPath roots.
Examples in the Wild
- mountaineer-auth: Login, signup, sessions, and password reset with pre-built views
- mountaineer-billing: Stripe subscriptions, metered usage, and webhook handling
- mountaineer-cloud: File storage and email across AWS, Cloudflare, DigitalOcean, and Resend
- mountaineer-exceptions: Exception pages with stack traces
Contributing a Plugin
To share your plugin:
- Open source your plugin on GitHub
- Publish to PyPI for easy installation
- Document configuration and supported versions with examples
- Submit to our community plugins list