firestore-schema-viewer 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +179 -0
- package/dist/favicon.svg +13 -0
- package/dist/fsv.es.js +35153 -0
- package/dist/fsv.umd.js +517 -0
- package/dist/index.html +25 -0
- package/dist/style.css +1 -0
- package/package.json +54 -0
- package/schema/collection.schema.json +43 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Juan Isidoro
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
# FireSchema
|
|
2
|
+
|
|
3
|
+
**Interactive schema viewer for Firestore databases.**
|
|
4
|
+
Like SwaggerUI, but for NoSQL.
|
|
5
|
+
|
|
6
|
+
Document your Firestore database structure using [JSON Schema](https://json-schema.org/) — the official standard for defining object structures — and visualize it with a beautiful dark-themed UI.
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Why FireSchema?
|
|
11
|
+
|
|
12
|
+
- **Firestore has no built-in schema documentation.** FireSchema fills that gap.
|
|
13
|
+
- **JSON Schema is an open standard** — not a proprietary format. Your schemas are portable and IDE-compatible.
|
|
14
|
+
- **Zero backend required** — it's a static SPA. Drop the files and open in a browser.
|
|
15
|
+
- **One file per collection** — folder structure mirrors your Firestore hierarchy 1:1.
|
|
16
|
+
|
|
17
|
+
## Quick Start
|
|
18
|
+
|
|
19
|
+
### 1. Install
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install firestore-schema-viewer
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
### 2. Create your schema files
|
|
26
|
+
|
|
27
|
+
Create a `schemas/` folder in your project. Each `.schema.json` file represents one Firestore collection:
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
schemas/
|
|
31
|
+
├── users.schema.json → /users/{userId}
|
|
32
|
+
├── users/
|
|
33
|
+
│ └── orders.schema.json → /users/{userId}/orders/{orderId}
|
|
34
|
+
└── products.schema.json → /products/{productId}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
**The folder structure mirrors Firestore.** Subcollections go inside a folder named after the parent collection. Firestore paths are inferred automatically — you never write them manually.
|
|
38
|
+
|
|
39
|
+
Example `schemas/users.schema.json`:
|
|
40
|
+
|
|
41
|
+
```json
|
|
42
|
+
{
|
|
43
|
+
"$schema": "https://raw.githubusercontent.com/juanisidoro/firestore-schema-viewer/main/schema/collection.schema.json",
|
|
44
|
+
"collection": "users",
|
|
45
|
+
"description": "Application users",
|
|
46
|
+
"documentCount": 1500,
|
|
47
|
+
"schema": {
|
|
48
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
49
|
+
"type": "object",
|
|
50
|
+
"properties": {
|
|
51
|
+
"email": { "type": "string", "format": "email" },
|
|
52
|
+
"displayName": { "type": "string" },
|
|
53
|
+
"role": { "type": "string", "enum": ["admin", "editor", "viewer"] },
|
|
54
|
+
"createdAt": { "type": "string", "format": "date-time" }
|
|
55
|
+
},
|
|
56
|
+
"required": ["email", "displayName", "role"]
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
> **Tip:** The `$schema` line at the top gives you autocomplete and validation in VS Code.
|
|
62
|
+
|
|
63
|
+
### 3. Create a viewer page
|
|
64
|
+
|
|
65
|
+
Create an `index.html` anywhere in your project:
|
|
66
|
+
|
|
67
|
+
```html
|
|
68
|
+
<!DOCTYPE html>
|
|
69
|
+
<html lang="en" class="dark">
|
|
70
|
+
<head>
|
|
71
|
+
<meta charset="UTF-8">
|
|
72
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
73
|
+
<title>My Database Schema</title>
|
|
74
|
+
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
|
|
75
|
+
<link rel="stylesheet" href="./node_modules/firestore-schema-viewer/dist/style.css">
|
|
76
|
+
</head>
|
|
77
|
+
<body>
|
|
78
|
+
<div id="schema-viewer"></div>
|
|
79
|
+
<script src="./node_modules/firestore-schema-viewer/dist/fsv.umd.js"></script>
|
|
80
|
+
<script>
|
|
81
|
+
FirestoreSchemaViewer.render('#schema-viewer', {
|
|
82
|
+
title: 'My Project',
|
|
83
|
+
schemas: [
|
|
84
|
+
'./schemas/users.schema.json',
|
|
85
|
+
'./schemas/users/orders.schema.json',
|
|
86
|
+
'./schemas/products.schema.json'
|
|
87
|
+
]
|
|
88
|
+
})
|
|
89
|
+
</script>
|
|
90
|
+
</body>
|
|
91
|
+
</html>
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Then serve it:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
npx serve .
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
That's it. Open the URL and you'll see your full database documentation.
|
|
101
|
+
|
|
102
|
+
## Schema File Format
|
|
103
|
+
|
|
104
|
+
Each `.schema.json` file has this structure:
|
|
105
|
+
|
|
106
|
+
| Field | Required | Description |
|
|
107
|
+
|---|---|---|
|
|
108
|
+
| `collection` | Yes | Collection name (e.g. `"users"`) |
|
|
109
|
+
| `schema` | Yes | Standard [JSON Schema](https://json-schema.org/draft/2020-12/schema) object |
|
|
110
|
+
| `description` | No | What this collection stores |
|
|
111
|
+
| `documentCount` | No | Approximate number of documents |
|
|
112
|
+
|
|
113
|
+
The `schema` field is plain **JSON Schema draft 2020-12**. You can use all standard features: `type`, `properties`, `required`, `enum`, `format`, `pattern`, `minimum`, `maximum`, nested `object` and `array` types, etc.
|
|
114
|
+
|
|
115
|
+
## How Paths Are Inferred
|
|
116
|
+
|
|
117
|
+
You never write Firestore paths manually. They're inferred from the file location:
|
|
118
|
+
|
|
119
|
+
| File path | Inferred Firestore path |
|
|
120
|
+
|---|---|
|
|
121
|
+
| `users.schema.json` | `/users/{userId}` |
|
|
122
|
+
| `users/orders.schema.json` | `/users/{userId}/orders/{orderId}` |
|
|
123
|
+
| `frontend-shops/products.schema.json` | `/frontend-shops/{frontend_shopId}/products/{productId}` |
|
|
124
|
+
|
|
125
|
+
## Usage with a Bundler
|
|
126
|
+
|
|
127
|
+
If your project uses a bundler (Vite, Webpack, etc.):
|
|
128
|
+
|
|
129
|
+
```js
|
|
130
|
+
import { render } from 'firestore-schema-viewer'
|
|
131
|
+
import 'firestore-schema-viewer/dist/style.css'
|
|
132
|
+
|
|
133
|
+
render('#schema-viewer', {
|
|
134
|
+
title: 'My App',
|
|
135
|
+
schemas: [
|
|
136
|
+
'./schemas/users.schema.json',
|
|
137
|
+
'./schemas/products.schema.json'
|
|
138
|
+
]
|
|
139
|
+
})
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Usage with CDN
|
|
143
|
+
|
|
144
|
+
No install needed — reference directly from jsDelivr:
|
|
145
|
+
|
|
146
|
+
```html
|
|
147
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/juanisidoro/firestore-schema-viewer/dist/style.css">
|
|
148
|
+
<script src="https://cdn.jsdelivr.net/gh/juanisidoro/firestore-schema-viewer/dist/fsv.umd.js"></script>
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## API
|
|
152
|
+
|
|
153
|
+
### `FirestoreSchemaViewer.render(selector, config)`
|
|
154
|
+
|
|
155
|
+
| Parameter | Type | Description |
|
|
156
|
+
|---|---|---|
|
|
157
|
+
| `selector` | `string` | CSS selector for the container element |
|
|
158
|
+
| `config.title` | `string` (optional) | Title shown in the sidebar header |
|
|
159
|
+
| `config.schemas` | `string[]` or `object[]` | URLs to `.schema.json` files, or inline collection objects |
|
|
160
|
+
|
|
161
|
+
## What You See
|
|
162
|
+
|
|
163
|
+
- **Sidebar** — navigable tree of all collections and subcollections
|
|
164
|
+
- **Stats bar** — total schemas, subcollections, fields, and documents
|
|
165
|
+
- **Schema tree** — expandable view of all fields with types, constraints, and descriptions
|
|
166
|
+
- **Raw JSON tab** — full JSON Schema source
|
|
167
|
+
- **Example generator** — auto-generated example documents from the schema
|
|
168
|
+
- **Copy buttons** — one-click copy for paths, empty objects, and examples
|
|
169
|
+
|
|
170
|
+
## Roadmap
|
|
171
|
+
|
|
172
|
+
- **v1.0** (current): Static viewer, dark theme, CDN support
|
|
173
|
+
- **Future** (based on demand): CLI tool, hot reload, schema validation, light theme, CI/CD integration
|
|
174
|
+
|
|
175
|
+
Want a feature? [Open an issue](https://github.com/juanisidoro/firestore-schema-viewer/issues).
|
|
176
|
+
|
|
177
|
+
## License
|
|
178
|
+
|
|
179
|
+
MIT
|
package/dist/favicon.svg
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
|
|
2
|
+
<!-- Fire shape -->
|
|
3
|
+
<path d="M16 2C16 2 10 8 10 14c0 2.5 1.2 4.7 3 6.2C12.4 18.5 12 16.8 12 15c0-3 4-7 4-7s4 4 4 7c0 1.8-.4 3.5-1 5.2 1.8-1.5 3-3.7 3-6.2C22 8 16 2 16 2z" fill="url(#fireGrad)" />
|
|
4
|
+
<!-- JSON braces -->
|
|
5
|
+
<text x="7" y="27" font-family="monospace" font-weight="700" font-size="11" fill="#f5f5f5" opacity="0.95">{</text>
|
|
6
|
+
<text x="21" y="27" font-family="monospace" font-weight="700" font-size="11" fill="#f5f5f5" opacity="0.95">}</text>
|
|
7
|
+
<defs>
|
|
8
|
+
<linearGradient id="fireGrad" x1="16" y1="2" x2="16" y2="22" gradientUnits="userSpaceOnUse">
|
|
9
|
+
<stop offset="0%" stop-color="#f59e0b" />
|
|
10
|
+
<stop offset="100%" stop-color="#ef4444" />
|
|
11
|
+
</linearGradient>
|
|
12
|
+
</defs>
|
|
13
|
+
</svg>
|