Static Site
✨ How to use: Copy this entire spec and paste it into your AI assistant (Claude, ChatGPT, etc.) when asking it to prepare your project for Niblit.ai deployment.
# Niblit.ai Deployment Spec: Static Site
You are deploying a static website (HTML, CSS, JavaScript) to Niblit.ai.
Follow these instructions EXACTLY. Do not deviate.
## Requirements
- Static files only (HTML, CSS, JavaScript, images)
- No server-side code
- Site is served via nginx
- Must listen on port 80
## Required Project Structure
```
your-project/
├── Dockerfile ← REQUIRED (use the template below exactly)
├── index.html ← REQUIRED (your main HTML file)
├── css/ ← Optional: stylesheets
├── js/ ← Optional: JavaScript files
├── images/ ← Optional: images
└── ... other static files
```
## Dockerfile (use this EXACTLY)
```dockerfile
FROM nginx:alpine
# Copy static files to nginx html directory
COPY . /usr/share/nginx/html
# Copy custom nginx config
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```
## nginx.conf (REQUIRED)
Create this file in your project root:
```nginx
server {
listen 80;
server_name localhost;
root /usr/share/nginx/html;
index index.html;
# Enable gzip compression
gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml;
# Cache static assets
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
# SPA support: serve index.html for all routes
location / {
try_files $uri $uri/ /index.html;
}
# Health check endpoint
location /health {
return 200 '{"status":"ok"}';
add_header Content-Type application/json;
}
}
```
## Basic index.html
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>My Site</title>
<link rel="stylesheet" href="css/style.css">
</head>
<body>
<h1>Hello from Niblit.ai!</h1>
<script src="js/app.js"></script>
</body>
</html>
```
## Single Page Applications (React, Vue, etc.)
If you're deploying a built SPA:
1. Build your app locally first (`npm run build`)
2. Copy only the `dist/` or `build/` folder contents to your project
3. Include the Dockerfile and nginx.conf
4. Upload the zip
Example structure for a React app:
```
your-project/
├── Dockerfile
├── nginx.conf
├── index.html ← from build/
├── static/
│ ├── css/
│ └── js/
└── assets/
```
## Environment Variables in JavaScript
Since this is static, you can't use server-side env vars. Options:
1. **Build-time variables**: Set them when building your SPA
2. **Config file**: Include a `config.js` that sets window variables:
```javascript
// config.js
window.CONFIG = {
apiUrl: 'https://api.example.com',
appName: 'My App'
};
```
```html
<script src="config.js"></script>
<script src="app.js"></script>
```
## What NOT to Include
- No `.env` files
- No `node_modules/` directory
- No `.git/` directory
- No source files (TypeScript, SCSS) — only compiled output
- No `src/` directory if using a build tool
**IMPORTANT**: Upload only the built/compiled files, not the source code.
## Testing Locally Before Upload
1. Build and run with Docker:
```bash
docker build -t my-site .
docker run -p 80:80 my-site
```
2. Visit http://localhost:80
3. If it works, create the zip and upload to Niblit.ai.
## Creating the Upload Zip
```bash
# From your project root (with built files):
zip -r my-site.zip . -x "*.git*" -x "node_modules/*" -x ".env" -x "src/*"
```
## Common Errors and Fixes
| Error | Fix |
|-------|-----|
| "Missing Dockerfile" | Add Dockerfile using template above |
| "Missing nginx.conf" | Create nginx.conf with the config above |
| "Missing index.html" | Ensure index.html is in the root |
| "Port mismatch" | Ensure nginx.conf has `listen 80` |
| "404 on refresh" | Add `try_files` directive for SPA support |
| "CSS/JS not loading" | Check file paths are relative, not absolute |
## Resource Limits
- **Free tier**: 256MB RAM, shared CPU, 1GB storage
- **Pro tier**: 512MB RAM, shared CPU, 1GB storage
- **Team tier**: 1GB RAM, 2 shared CPUs, 5GB storage
Free tier apps sleep after 5 minutes of no traffic and wake automatically (1-2 second cold start for static sites).
## Example Site
See the `example/` directory for a complete working example.