Generate token-efficient, LLM-optimized documentation from official Supabase SDK specifications
Transforms Supabase's official OpenRef YAML specifications into token-efficient, context-rich documentation specifically optimized for Large Language Models (Claude, GPT, etc.).
Key Features:
- Inline SQL schemas and JSON responses for better context
- Token-optimized format (minimal decorations, maximum information)
- Modular output (separate files for auth, database, storage, etc.)
- Automated fetching from Supabase's official specs
- Complete support for all 6 Supabase SDKs across 11 versions
Complete support for all 6 Supabase SDKs across 11 versions:
- JavaScript/TypeScript: v1, v2 (2 versions)
- Kotlin: v1, v2, v3 (3 versions)
- Dart/Flutter: v1, v2 (2 versions)
- C#: v0, v1 (2 versions)
- Python: v2 (1 version)
- Swift: v1, v2 (2 versions)
Total: 11 specification files supported
git clone https://github.com/Zyepher/supabase-llm-docs
cd supabase-llm-docs
pip install -e .List available SDKs:
supabase-llm-docs list-sdksGenerate specific SDK (latest version):
supabase-llm-docs generate --sdk javascript
supabase-llm-docs generate --sdk swift
supabase-llm-docs generate --sdk kotlinGenerate specific version:
supabase-llm-docs generate --sdk javascript --version v2
supabase-llm-docs generate --sdk kotlin --version v3Generate all versions:
supabase-llm-docs generate --sdk javascript --version allGenerate everything:
supabase-llm-docs generate --sdk all --version allUsing Make (recommended):
make list # List all SDKs and versions
make run-js # Generate JavaScript (latest)
make run-kotlin # Generate Kotlin (latest)
make run-swift # Generate Swift (latest)
make run # Generate all SDKs (all versions)Generated documentation is saved in:
output/
├── javascript/
│ ├── v2/
│ │ ├── parsed/
│ │ │ └── javascript-v2-spec.json
│ │ └── llm-docs/
│ │ ├── supabase-js-v2-initializing-llms.txt
│ │ ├── supabase-js-v2-database-llms.txt
│ │ ├── supabase-js-v2-auth-llms.txt
│ │ ├── supabase-js-v2-storage-llms.txt
│ │ ├── supabase-js-v2-realtime-llms.txt
│ │ ├── supabase-js-v2-edge-functions-llms.txt
│ │ └── supabase-js-v2-full-llms.txt
│ └── v1/
│ └── ...
├── kotlin/
│ ├── v3/
│ ├── v2/
│ └── v1/
├── swift/
├── dart/
├── csharp/
└── python/
Copy the generated .txt files into your LLM context:
For complete reference:
- Use
*-full-llms.txt- includes all SDK functionality
For specific topics:
- Use individual module files (auth, database, storage, etc.)
- More token-efficient when you only need specific functionality
Example with Claude:
Paste supabase-js-v2-database-llms.txt into your conversation, then ask:
"How do I query a PostgreSQL table with filters in JavaScript?"
The generated docs use an LLM-optimized format:
<SYSTEM>This is the developer documentation for Supabase JavaScript Client v2 - Database Operations.</SYSTEM>
# Supabase JavaScript Client v2 Database Operations Documentation
# 1. Fetch data: select()
## 1.1. Getting your data
```javascript
const { data, error } = await supabase
.from('countries')
.select()
// Data Source
/*
create table countries (
id int8 primary key,
name text
);
*/
// Response
/*
{
"data": [{"id": 1, "name": "Afghanistan"}],
"status": 200
}
*/
**Why this format?**
- System prompts provide context to LLMs
- SQL schemas embedded in code blocks
- Expected responses inline
- Hierarchical numbering for navigation
- Token-efficient (no decorative elements)
## Development
### Setup Development Environment
```bash
# Install with development dependencies
pip install -e ".[dev]"
make install # Install package
make dev-install # Install with dev dependencies
make clean # Remove generated files
make test # Run tests
make lint # Run linters
make format # Format code
make list # List all SDKs and versions
make run # Generate docs for all SDKs
make run-js # Generate JavaScript docs (latest)
make run-kotlin # Generate Kotlin docs (latest)
make run-swift # Generate Swift docs (latest)make test
# Or with pytest directly
pytest# Lint code
make lint
# Format code
make formatThe tool uses configuration-driven design with zero code changes needed to add SDKs.
sdks:
javascript:
name: "JavaScript"
language: javascript
versions:
v2:
display_name: "Supabase JavaScript Client v2"
spec:
url: "https://raw.githubusercontent.com/supabase/supabase/master/apps/docs/spec/supabase_js_v2.yml"
output:
base_dir: "javascript"
filename_prefix: "supabase-js-v2"
v1:
display_name: "Supabase JavaScript Client v1"
spec:
url: "https://raw.githubusercontent.com/supabase/supabase/master/apps/docs/spec/supabase_js_v1.yml"
output:
base_dir: "javascript"
filename_prefix: "supabase-js-v1"Controls how operations are grouped into modules:
categories:
database:
title: "Database Operations"
description: "Query and manipulate data using PostgREST"
operations:
- select
- insert
- update
- delete
# ... more operations
order: 4supabase-llm-docs/
├── src/supabase_llm_docs/ # Core Python package
│ ├── cli.py # Command-line interface
│ ├── core/
│ │ ├── parser.py # OpenRef YAML parser
│ │ ├── formatter.py # LLM documentation formatter
│ │ └── models.py # Data models
│ ├── config/
│ │ ├── loader.py # Configuration management
│ │ └── schemas.py # Pydantic validation schemas
│ └── utils/
│ ├── logger.py # Logging setup
│ └── fetcher.py # HTTP spec fetching
├── config/
│ ├── sdks.yaml # SDK definitions
│ └── categories.yaml # Module categorization
├── output/ # Generated documentation
├── tests/ # Test suite
├── pyproject.toml # Project configuration
├── Makefile # Development commands
└── README.md # This file
The tool follows a three-stage pipeline:
- Fetch: Download latest YAML specs from GitHub (or use local files)
- Parse: Extract operations, examples, and metadata into structured data
- Format: Transform into LLM-optimized documentation with inline context
All configuration is data-driven via YAML files, making it easy to:
- Add new SDKs without code changes
- Modify operation categorization
- Customize output formats
- Extend functionality
Generate LLM documentation for specified SDK(s) and version(s).
supabase-llm-docs generate --sdk <sdk_name> [--version <version>]
Options:
--sdk TEXT SDK to generate (javascript, kotlin, swift, dart, csharp, python, or 'all')
--version TEXT Version to generate (v1, v2, v3, 'latest', or 'all') [default: latest]
--config-dir PATH Configuration directory [default: config]
--output-dir PATH Output directory [default: output]
-v, --verbose Enable verbose loggingList all configured SDKs and their versions.
supabase-llm-docs list-sdksValidate SDK specification.
supabase-llm-docs validate <sdk_name> [--version <version>]Contributions are welcome! Please see CONTRIBUTING.md for:
- Development workflow
- Code style guidelines
- Testing requirements
- Pull request process
- Fork the repository
- Create a feature branch:
git checkout -b feature/your-feature - Make your changes
- Run tests:
make test - Format code:
make format - Commit:
git commit -m "feat: your feature" - Push and create a Pull Request
MIT License - see LICENSE for details.
- Built for the Supabase ecosystem
- Uses Supabase's OpenRef 0.1 specification format
- Official specs: supabase/supabase/apps/docs/spec
See CHANGELOG.md for version history and release notes.