# FluidKit
<div align="center">
<img src="https://azure-deliberate-dog-514.mypinata.cloud/ipfs/bafkreiay74jzankyzj2zh4zemmpidafbsrcr4hwjxnl5e3qk32xyi6t3hi" alt="FluidKit Logo" width="125">
</div>
**Web development for the pythoniers**
FluidKit provides tooling for building modern, highly optimized fullstack web applications with Python + the power of SvelteKit. Automatic type-safe client generation and environment-aware proxying make FastAPI + SvelteKit feel like a unified framework.
```bash
pip install fluidkit
```
## Build Modern Web Apps with Python
Access the JavaScript ecosystem for UI while keeping all your business logic in Python. No Node.js backend knowledge required.
### 📦 **Client Generation** - For any project setup
```python
import fluidkit
fluidkit.integrate(app) # Generates portable TypeScript clients
```
### 🌐 **Full-Stack Development** - Python + SvelteKit unified
```python
import fluidkit
fluidkit.integrate(app, enable_fullstack=True) # Complete fullstack tooling
```
## 🚀 Full-Stack Get Started
**Prerequisites:** Node.js, [uv](https://docs.astral.sh/uv/) (preferred) or Poetry
```bash
# 1. Create SvelteKit project
npx sv create my-app
cd my-app
# 2. Initialize Python environment
uv init # or: poetry init
uv add fluidkit # or: poetry add fluidkit
# 3. Create Python backend
```
**Folder structure:**
```
src/routes/
├── +page.svelte # Svelte component
├── app.api.py # Python API logic
└── app.api.ts # Auto-generated client (by FluidKit)
```
**Create `src/app.py`:**
```python
import fluidkit
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
fluidkit.integrate(app, enable_fullstack=True)
if __name__ == "__main__":
import uvicorn
uvicorn.run("app:app", host="0.0.0.0", port=8000, reload=True)
```
**Create `src/routes/hello.api.py`:**
```python
from fastapi import APIRouter
from pydantic import BaseModel
router = APIRouter()
class Message(BaseModel):
text: str
@router.get("/hello")
async def get_message() -> Message:
return Message(text="Hello from Python!")
```
**Use in `src/routes/+page.svelte`:**
```svelte
<script>
import { get_message } from './hello.api';
let message = $state('');
get_message().then(result => {
if (result.success) message = result.data.text;
});
</script>
<h1>{message}</h1>
```
```bash
# 4. Start development
uv run python src/app.py # Start Python backend
npm run dev # Start SvelteKit (separate terminal)
```
**You're ready!** Visit `http://localhost:5173` to see your full-stack app. Visit `http://localhost:5173/proxy/docs` to see fastapi swagger UI.
## The FluidKit Experience
**Write your backend in Python:**
```python
from uuid import UUID
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class User(BaseModel):
id: UUID
name: str
email: str
@app.get("/users/{user_id}")
async def get_user(user_id: UUID) -> User:
# Your Python logic - database, validation, etc.
return fetch_user_from_database(user_id)
import fluidkit
fluidkit.integrate(app, enable_fullstack=True)
```
**Use directly in SvelteKit like local functions:**
```svelte
<script>
import { get_user } from './users.api';
let userId = $state('');
let user = $state(null);
let error = $state('');
function loadUser() {
error = '';
get_user(userId).then(result => {
if (result.success) {
user = result.data;
} else {
error = result.error;
}
});
}
</script>
<input bind:value={userId} placeholder="Enter user ID" />
<button onclick={loadUser}>Load User</button>
{#if error}
<p style="color: red;">{error}</p>
{/if}
{#if user}
<div>
<h3>{user.name}</h3>
<p>{user.email}</p>
</div>
{/if}
```
**FluidKit automatically generates:**
```typescript
// Full type safety from Python → TypeScript
export interface User {
id: FluidTypes.UUID;
name: string;
email: string;
}
export const get_user = async (user_id: FluidTypes.UUID): Promise<ApiResult<User>> => {
// Environment-aware: direct FastAPI in SSR, proxied in browser
};
```
## ✨ What's New in v0.2.6
- 🔄 **[Streaming Support](docs/streaming.md)** - Server-Sent Events, file downloads, JSON streaming
- 🏷️ **[FluidTypes Namespace](docs/types.md)** - Clean handling of external types (UUID, Decimal, DateTime)
- 📁 **[Enhanced Auto-Discovery](docs/auto-discovery.md)** - SvelteKit-style folder routing with parameter validation
- ⚡ **Simplified Configuration** - Zero config for client generation, rich config for fullstack
## 🚀 Key Features
- **Unified Development Experience** - Write Python, get modern SvelteKit web apps
- **Complete Type Safety** - Python types → TypeScript interfaces automatically
- **Environment-Aware Proxying** - Same client works in SSR and browser seamlessly
- **Streaming First-Class** - SSE, file downloads, JSON streaming support
- **Smart External Types** - UUID, Decimal, DateTime via clean `FluidTypes` namespace
- **Auto-Discovery** - SvelteKit-style file-based routing patterns
- **Zero Node.js Knowledge Required** - Pure Python backend development
- **Highly Optimized** - SvelteKit's SSR, hydration, code splitting, and performance
## 🛠️ Two Development Modes
### **Client Generation Only**
Perfect for existing projects, microservices, or when frontend/backend deploy separately:
```python
# Generates portable TypeScript clients
fluidkit.integrate(app)
```
- Clean `.fluidkit/` output directory
- Copy generated clients to any frontend project
- Works with React, Vue, vanilla TypeScript, etc.
- Full type safety across the API boundary
### **Full-Stack Development**
Unified Python + SvelteKit development with seamless integration:
```python
# Enables complete fullstack tooling
fluidkit.integrate(app, enable_fullstack=True)
```
- Auto-generated SvelteKit proxy routes
- Environment-aware client (SSR + browser)
- Hot reload across frontend and backend
- Production deployment optimization
- Auto-discovery of API routes
## 📚 Documentation
| Guide | Description |
|-------|-------------|
| **[Full-Stack Development](docs/fullstack.md)** | Complete SvelteKit integration, deployment, environment setup |
| **[Streaming Clients](docs/streaming.md)** | SSE, file downloads, JSON streaming patterns |
| **[Configuration](docs/configuration.md)** | Config reference, strategies, environments |
| **[Auto-Discovery](docs/auto-discovery.md)** | File patterns, routing conventions, parameter validation |
| **[Type System](docs/types.md)** | FluidTypes namespace, external type handling |
## 🛣️ Roadmap
- ✅ **TypeScript Client Generation** (current)
- ✅ **SvelteKit Full-Stack Integration** (current)
- 🚧 **CLI Tooling** - Project templates, deployment orchestration
- 🚧 **Python Client Generation** - Full Python ecosystem
- 🚧 **Advanced Streaming** - WebSockets, real-time features
**Build modern, type-safe web applications using the Python ecosystem you know + the SvelteKit performance you want.**
Raw data
{
"_id": null,
"home_page": null,
"name": "fluidkit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "fastapi, typescript, code-generation, full-stack, type-safety, sveltekit, nextjs, nuxtjs",
"author": null,
"author_email": "Aswanth Manoj <aswanthmanoj51@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4e/47/40c8259aeed174a376e9d29a7fec68ae3cc331f9c417fe575394f07603fa/fluidkit-0.2.6.tar.gz",
"platform": null,
"description": "# FluidKit\r\n\r\n<div align=\"center\">\r\n <img src=\"https://azure-deliberate-dog-514.mypinata.cloud/ipfs/bafkreiay74jzankyzj2zh4zemmpidafbsrcr4hwjxnl5e3qk32xyi6t3hi\" alt=\"FluidKit Logo\" width=\"125\">\r\n</div>\r\n\r\n**Web development for the pythoniers**\r\n\r\nFluidKit provides tooling for building modern, highly optimized fullstack web applications with Python + the power of SvelteKit. Automatic type-safe client generation and environment-aware proxying make FastAPI + SvelteKit feel like a unified framework.\r\n\r\n```bash\r\npip install fluidkit\r\n```\r\n\r\n## Build Modern Web Apps with Python\r\n\r\nAccess the JavaScript ecosystem for UI while keeping all your business logic in Python. No Node.js backend knowledge required.\r\n\r\n### \ud83d\udce6 **Client Generation** - For any project setup\r\n```python\r\nimport fluidkit\r\nfluidkit.integrate(app) # Generates portable TypeScript clients\r\n```\r\n\r\n### \ud83c\udf10 **Full-Stack Development** - Python + SvelteKit unified\r\n```python\r\nimport fluidkit\r\nfluidkit.integrate(app, enable_fullstack=True) # Complete fullstack tooling\r\n```\r\n\r\n## \ud83d\ude80 Full-Stack Get Started\r\n\r\n**Prerequisites:** Node.js, [uv](https://docs.astral.sh/uv/) (preferred) or Poetry\r\n\r\n```bash\r\n# 1. Create SvelteKit project\r\nnpx sv create my-app\r\ncd my-app\r\n\r\n# 2. Initialize Python environment\r\nuv init # or: poetry init\r\nuv add fluidkit # or: poetry add fluidkit\r\n\r\n# 3. Create Python backend\r\n```\r\n\r\n**Folder structure:**\r\n```\r\nsrc/routes/\r\n\u251c\u2500\u2500 +page.svelte # Svelte component\r\n\u251c\u2500\u2500 app.api.py # Python API logic \r\n\u2514\u2500\u2500 app.api.ts # Auto-generated client (by FluidKit)\r\n```\r\n\r\n**Create `src/app.py`:**\r\n```python\r\nimport fluidkit\r\nfrom fastapi import FastAPI\r\nfrom pydantic import BaseModel\r\n\r\napp = FastAPI()\r\n\r\nfluidkit.integrate(app, enable_fullstack=True)\r\n\r\nif __name__ == \"__main__\":\r\n import uvicorn\r\n uvicorn.run(\"app:app\", host=\"0.0.0.0\", port=8000, reload=True)\r\n```\r\n\r\n**Create `src/routes/hello.api.py`:**\r\n```python\r\nfrom fastapi import APIRouter\r\nfrom pydantic import BaseModel\r\n\r\nrouter = APIRouter()\r\n\r\nclass Message(BaseModel):\r\n text: str\r\n\r\n@router.get(\"/hello\")\r\nasync def get_message() -> Message:\r\n return Message(text=\"Hello from Python!\")\r\n```\r\n\r\n**Use in `src/routes/+page.svelte`:**\r\n```svelte\r\n<script>\r\n import { get_message } from './hello.api';\r\n \r\n let message = $state('');\r\n \r\n get_message().then(result => {\r\n if (result.success) message = result.data.text;\r\n });\r\n</script>\r\n\r\n<h1>{message}</h1>\r\n```\r\n\r\n```bash\r\n# 4. Start development\r\nuv run python src/app.py # Start Python backend\r\nnpm run dev # Start SvelteKit (separate terminal)\r\n```\r\n\r\n**You're ready!** Visit `http://localhost:5173` to see your full-stack app. Visit `http://localhost:5173/proxy/docs` to see fastapi swagger UI.\r\n\r\n\r\n## The FluidKit Experience\r\n\r\n**Write your backend in Python:**\r\n```python\r\nfrom uuid import UUID\r\nfrom fastapi import FastAPI\r\nfrom pydantic import BaseModel\r\n\r\napp = FastAPI()\r\n\r\nclass User(BaseModel):\r\n id: UUID\r\n name: str\r\n email: str\r\n\r\n@app.get(\"/users/{user_id}\")\r\nasync def get_user(user_id: UUID) -> User:\r\n # Your Python logic - database, validation, etc.\r\n return fetch_user_from_database(user_id)\r\n\r\nimport fluidkit\r\nfluidkit.integrate(app, enable_fullstack=True)\r\n```\r\n\r\n**Use directly in SvelteKit like local functions:**\r\n```svelte\r\n<script>\r\n import { get_user } from './users.api';\r\n \r\n let userId = $state('');\r\n let user = $state(null);\r\n let error = $state('');\r\n \r\n function loadUser() {\r\n error = '';\r\n get_user(userId).then(result => {\r\n if (result.success) {\r\n user = result.data;\r\n } else {\r\n error = result.error;\r\n }\r\n });\r\n }\r\n</script>\r\n\r\n<input bind:value={userId} placeholder=\"Enter user ID\" />\r\n<button onclick={loadUser}>Load User</button>\r\n\r\n{#if error}\r\n <p style=\"color: red;\">{error}</p>\r\n{/if}\r\n\r\n{#if user}\r\n <div>\r\n <h3>{user.name}</h3>\r\n <p>{user.email}</p>\r\n </div>\r\n{/if}\r\n```\r\n\r\n**FluidKit automatically generates:**\r\n```typescript\r\n// Full type safety from Python \u2192 TypeScript\r\nexport interface User {\r\n id: FluidTypes.UUID;\r\n name: string;\r\n email: string;\r\n}\r\n\r\nexport const get_user = async (user_id: FluidTypes.UUID): Promise<ApiResult<User>> => {\r\n // Environment-aware: direct FastAPI in SSR, proxied in browser\r\n};\r\n```\r\n\r\n## \u2728 What's New in v0.2.6\r\n\r\n- \ud83d\udd04 **[Streaming Support](docs/streaming.md)** - Server-Sent Events, file downloads, JSON streaming\r\n- \ud83c\udff7\ufe0f **[FluidTypes Namespace](docs/types.md)** - Clean handling of external types (UUID, Decimal, DateTime)\r\n- \ud83d\udcc1 **[Enhanced Auto-Discovery](docs/auto-discovery.md)** - SvelteKit-style folder routing with parameter validation\r\n- \u26a1 **Simplified Configuration** - Zero config for client generation, rich config for fullstack\r\n\r\n## \ud83d\ude80 Key Features\r\n\r\n- **Unified Development Experience** - Write Python, get modern SvelteKit web apps\r\n- **Complete Type Safety** - Python types \u2192 TypeScript interfaces automatically \r\n- **Environment-Aware Proxying** - Same client works in SSR and browser seamlessly\r\n- **Streaming First-Class** - SSE, file downloads, JSON streaming support\r\n- **Smart External Types** - UUID, Decimal, DateTime via clean `FluidTypes` namespace\r\n- **Auto-Discovery** - SvelteKit-style file-based routing patterns\r\n- **Zero Node.js Knowledge Required** - Pure Python backend development\r\n- **Highly Optimized** - SvelteKit's SSR, hydration, code splitting, and performance\r\n\r\n## \ud83d\udee0\ufe0f Two Development Modes\r\n\r\n### **Client Generation Only**\r\nPerfect for existing projects, microservices, or when frontend/backend deploy separately:\r\n\r\n```python\r\n# Generates portable TypeScript clients\r\nfluidkit.integrate(app)\r\n```\r\n- Clean `.fluidkit/` output directory\r\n- Copy generated clients to any frontend project \r\n- Works with React, Vue, vanilla TypeScript, etc.\r\n- Full type safety across the API boundary\r\n\r\n### **Full-Stack Development**\r\nUnified Python + SvelteKit development with seamless integration:\r\n\r\n```python\r\n# Enables complete fullstack tooling\r\nfluidkit.integrate(app, enable_fullstack=True)\r\n```\r\n- Auto-generated SvelteKit proxy routes\r\n- Environment-aware client (SSR + browser)\r\n- Hot reload across frontend and backend\r\n- Production deployment optimization\r\n- Auto-discovery of API routes\r\n\r\n## \ud83d\udcda Documentation\r\n\r\n| Guide | Description |\r\n|-------|-------------|\r\n| **[Full-Stack Development](docs/fullstack.md)** | Complete SvelteKit integration, deployment, environment setup |\r\n| **[Streaming Clients](docs/streaming.md)** | SSE, file downloads, JSON streaming patterns |\r\n| **[Configuration](docs/configuration.md)** | Config reference, strategies, environments |\r\n| **[Auto-Discovery](docs/auto-discovery.md)** | File patterns, routing conventions, parameter validation |\r\n| **[Type System](docs/types.md)** | FluidTypes namespace, external type handling |\r\n\r\n## \ud83d\udee3\ufe0f Roadmap\r\n\r\n- \u2705 **TypeScript Client Generation** (current)\r\n- \u2705 **SvelteKit Full-Stack Integration** (current) \r\n- \ud83d\udea7 **CLI Tooling** - Project templates, deployment orchestration\r\n- \ud83d\udea7 **Python Client Generation** - Full Python ecosystem\r\n- \ud83d\udea7 **Advanced Streaming** - WebSockets, real-time features\r\n\r\n\r\n**Build modern, type-safe web applications using the Python ecosystem you know + the SvelteKit performance you want.**\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Automatic TypeScript client generation for FastAPI through runtime introspection",
"version": "0.2.6",
"project_urls": {
"Documentation": "https://github.com/AswanthManoj/Fluidkit#readme",
"Homepage": "https://github.com/AswanthManoj/Fluidkit",
"Issues": "https://github.com/AswanthManoj/Fluidkit/issues",
"Repository": "https://github.com/AswanthManoj/Fluidkit"
},
"split_keywords": [
"fastapi",
" typescript",
" code-generation",
" full-stack",
" type-safety",
" sveltekit",
" nextjs",
" nuxtjs"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6152cce438449c161c4aa0f75a458765f8c6c38c2bb0f261e823231c9422acc5",
"md5": "59172dc83611327ae961eb0288e99bd2",
"sha256": "f6e786247ef1eeb3ac18882f97889f221c9600d9aab5c0fa9b2ef2e69ad51e36"
},
"downloads": -1,
"filename": "fluidkit-0.2.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "59172dc83611327ae961eb0288e99bd2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 69873,
"upload_time": "2025-07-28T19:16:53",
"upload_time_iso_8601": "2025-07-28T19:16:53.165975Z",
"url": "https://files.pythonhosted.org/packages/61/52/cce438449c161c4aa0f75a458765f8c6c38c2bb0f261e823231c9422acc5/fluidkit-0.2.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4e4740c8259aeed174a376e9d29a7fec68ae3cc331f9c417fe575394f07603fa",
"md5": "a00e900998347e0411a754fb1f8cd2f3",
"sha256": "6082e8e585a4c2df1157e4134ba763432f9ef6e53d6ac982a0e8ee615ba2f5d9"
},
"downloads": -1,
"filename": "fluidkit-0.2.6.tar.gz",
"has_sig": false,
"md5_digest": "a00e900998347e0411a754fb1f8cd2f3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 68115,
"upload_time": "2025-07-28T19:16:54",
"upload_time_iso_8601": "2025-07-28T19:16:54.541580Z",
"url": "https://files.pythonhosted.org/packages/4e/47/40c8259aeed174a376e9d29a7fec68ae3cc331f9c417fe575394f07603fa/fluidkit-0.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 19:16:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AswanthManoj",
"github_project": "Fluidkit#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "fluidkit"
}
JSON
