1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396# 🚀 Deployment Guide
Comprehensive guide for deploying the Blend Design System documentation (Ascent) and Storybook to Firebase Hosting.
## 🎯 Quick Start
```bash
# Deploy to staging
npm run deploy:dev
# Deploy to production
npm run deploy:prod
```
**URLs:**
- 📚 Production Docs: https://juspay.design
- 📖 Production Storybook: https://juspay.design/storybook
- 📚 Staging Docs: https://blend-staging.web.app
- 📖 Staging Storybook: https://blend-staging.web.app/storybook
## 📋 Table of Contents
- [Overview](#overview)
- [Setup](#setup)
- [Deployment](#deployment)
- [Content Management](#content-management)
- [Security](#security)
- [Troubleshooting](#troubleshooting)
- [Architecture](#architecture)
## Overview
### Architecture
```
┌─────────────────┐ ┌──────────────────┐
│ Documentation │ │ Storybook │
│ (Ascent) │ │ (Storybook 8) │
│ Next.js │ │ │
└────────┬────────┘ └────────┬─────────┘
│ │
└───────────┬───────────┘
│
┌──────▼──────┐
│ Firebase │
│ Hosting │
└─────────────┘
```
- **Single Firebase Project**: `storybook-452807`
- **Path-based Routing**:
- `/` → Ascent documentation
- `/storybook/*` → Storybook
- **Static Export**: Both apps are built as static sites
- **Client-side Search**: No server required
### Environments
| Environment | Target | URL | Purpose |
| ----------- | --------------- | ----------------------------- | ---------------- |
| Production | `blend-prod` | https://juspay.design | Live Site |
| Staging | `blend-staging` | https://blend-staging.web.app | Testing & Review |
## Setup
### Prerequisites
1. **Install Dependencies**
```bash
# Install pnpm if not already installed
npm install -g pnpm
# Install project dependencies
pnpm install
# Install Firebase CLI
npm install -g firebase-tools
```
2. **Firebase Login**
```bash
firebase login
```
### Environment Configuration
The project uses two environment files:
- `.env.dev` - Staging environment configuration
- `.env.prod` - Production environment configuration
These files contain:
```env
# Example .env.dev
FIREBASE_PROJECT_ID=storybook-452807
FIREBASE_HOSTING_TARGET=blend-staging
DEPLOY_URL=https://blend-staging.web.app
# Example .env.prod
FIREBASE_PROJECT_ID=storybook-452807
FIREBASE_HOSTING_TARGET=blend-prod
DEPLOY_URL=https://juspay.design
```
## Deployment
### 🏃 Local Development
```bash
# Ascent documentation development
npm run ascent:dev
# Storybook development
npm run storybook
# Build everything
npm run build:all
# Build specific apps
npm run build:ascent
npm run build:storybook
```
### 🚀 Manual Deployment
The deployment process uses a unified script (`deploy.sh`) that:
1. Loads environment variables from `.env.dev` or `.env.prod`
2. Builds Ascent documentation (with search index generation)
3. Builds Storybook
4. Combines both builds into a single `dist/` directory
5. Deploys to Firebase Hosting
#### Deploy Commands
```bash
# Deploy to staging
npm run deploy:dev
# Deploy to production
npm run deploy:prod
```
### 📦 What Gets Deployed
1. **Ascent Documentation** (`/`)
- Next.js static export
- MDX documentation pages
- Client-side search with pre-built index
- Component examples and previews
2. **Storybook** (`/storybook`)
- Component stories
- Interactive playground
- Design tokens
- Usage examples
3. **Static Assets**
- Fonts
- Images
- Search index (`search-index.json`)
## Content Management
### 📝 Adding Documentation
1. **Create MDX File**
```bash
# Create new component doc
touch apps/ascent/app/docs/content/components/NewComponent.mdx
```
2. **MDX Format**
````mdx
---
title: Component Name
description: Brief description for search
category: Components
tags: [tag1, tag2]
---
# Component Name
Component description and usage.
## Usage
```jsx
import { Component } from '@juspay/blend-design-system'
;<Component prop="value" />
```
## Props
<DocsTypeTable>...props documentation...</DocsTypeTable>
````
3. **Update Navigation**
Edit `apps/ascent/app/docs/content/config.json` to add your new component to the navigation.
### 🔍 Search System
The search system uses a build-time generated index:
- **What's Indexed**: All MDX content including titles, headings, content, and tags
- **When**: At build time via `prebuild` script
- **How**: Static JSON file loaded client-side
- **Script**: `apps/ascent/scripts/generate-search-index.mjs`
## Security
### 🔒 Security Headers
All deployments include comprehensive security headers configured in `firebase.json`:
```
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: camera=(), microphone=(), geolocation=()
Strict-Transport-Security: max-age=31536000; includeSubDomains (production only)
Content-Security-Policy: [configured for your needs]
```
### 🔐 Environment Variables
- Never commit `.env.dev` or `.env.prod` files (they're gitignored)
- Store secrets in GitHub Secrets for CI/CD
- Rotate credentials regularly
### 📊 Cache Strategy
| Resource | Staging | Production |
| -------- | -------- | ---------- |
| HTML | No cache | No cache |
| JS/CSS | 1 hour | 1 year |
| Images | 1 day | 1 week |
| Fonts | 1 week | 1 year |
## Troubleshooting
### Common Issues
#### Build Failures
```bash
# Clean everything and try again
npm run clean
pnpm install
npm run build:all
```
#### Search Not Working
The search index is generated at build time. If search isn't working:
1. Check if `apps/ascent/public/search-index.json` exists after build
2. Ensure the `prebuild` script runs: `node scripts/generate-search-index.mjs`
3. Verify MDX files have proper frontmatter
#### SSR/Window Not Defined Errors
If you encounter "window is not defined" errors during build:
1. Preview components use dynamic imports with `ssr: false` via `PreviewWrapper`
2. All preview components are wrapped to prevent SSR issues
3. The `PreviewWrapper` component handles client-side rendering
#### Firebase Authentication Failed
```bash
firebase login --reauth
firebase projects:list
```
#### Deployment Fails
- Check Firebase Console for quota limits
- Ensure `.env.dev` and `.env.prod` files exist
- Verify Firebase hosting targets are configured
- Make sure `deploy.sh` is executable: `chmod +x deploy.sh`
### Debug Commands
```bash
# Check Firebase project
firebase projects:list
# Check hosting targets
firebase target:list
# Test builds locally
npm run build:ascent
npm run build:storybook
# View Firebase hosting releases
firebase hosting:releases:list --site blend-staging
firebase hosting:releases:list --site blend-prod
```
## Architecture
### Deployment Structure
```
blend-design-system/
├── deploy.sh # Unified deployment script
├── .env.dev # Staging environment config
├── .env.prod # Production environment config
├── dist/ # Combined deployment directory
│ ├── index.html # Ascent root
│ ├── search-index.json # Search index
│ ├── [ascent files] # All Ascent static files
│ └── storybook/ # Storybook subdirectory
│ └── index.html # Storybook root
└── apps/
├── ascent/ # Main documentation
│ ├── out/ # Next.js build output
│ └── scripts/ # Build scripts
│ └── generate-search-index.mjs
└── storybook/ # Component library
└── storybook-static/ # Storybook build output
```
### Firebase Configuration
**`.firebaserc`**
```json
{
"projects": {
"default": "storybook-452807"
},
"targets": {
"storybook-452807": {
"hosting": {
"blend-staging": ["blend-staging"],
"blend-prod": ["blend-prod"]
}
}
}
}
```
**`firebase.json`**
- Configures rewrites for path-based routing
- Sets security headers
- Defines cache policies
- Handles `/storybook` path routing
### NPM Scripts
```json
{
"scripts": {
// Development
"ascent:dev": "cd apps/ascent && npm run dev",
"storybook": "cd apps/storybook && pnpm dev",
// Building
"build:ascent": "cd apps/ascent && npm run build",
"build:storybook": "cd apps/storybook && pnpm build-storybook",
"build:all": "npm run build:ascent && npm run build:storybook",
// Deployment
"deploy:dev": "./deploy.sh dev",
"deploy:prod": "./deploy.sh prod",
// Utilities
"clean": "turbo run clean && rm -rf node_modules dist apps/ascent/out apps/storybook/storybook-static"
}
}
```
## 🌐 Custom Domain
The production deployment is configured with the custom domain `juspay.design`. The DNS configuration and SSL certificates are managed through Firebase Hosting.
## 📚 Resources
- [Firebase Hosting Documentation](https://firebase.google.com/docs/hosting)
- [Next.js Static Export](https://nextjs.org/docs/app/building-your-application/deploying/static-exports)
- [Storybook Deployment](https://storybook.js.org/docs/react/sharing/publish-storybook)
---
Last updated: January 2025