docs: expand Deployments with StatikAPI Cloud info and provider guides

Author: zonayedpca

docs/_meta.json

@@ -2,6 +2,6 @@
   "name": "StatikAPI",
   "description": "Build static JSON endpoints from filesystem modules — like Next.js static export, but for APIs.",
   "version": "0.4.0",
-  "lastUpdated": "2025-11-08T00:40:00.000Z",
+  "lastUpdated": "2025-11-08T01:00:00.000Z",
   "repo": "https://github.com/zonayedpca/statikapi"
 }

docs/config.mdx

@@ -141,11 +141,3 @@ You can freely use **.ts / .tsx** route files. The CLI transpiles on the fly and
 - **`srcDir` and `outDir` must differ** — point them at different folders.
 - **Dynamic routes not emitting** — ensure the module exports `paths()` that returns **strings** (or arrays of strings for catch‑all). See **Routes** docs.
 - **Non‑serializable value** — only plain objects/arrays, finite numbers, strings, booleans, or `null`. No functions, symbols, BigInt, Dates, classes, or cycles.
-
----
-
-## See also
-
-- **[CLI → StatikAPI (Core)](./cli/statikapi)** for flags and dev/build usage
-- **[Routes](./routes/index)** for file → URL mapping rules
-- **[Deployments](./deployments/index)** for hosting static JSON

docs/deployments/amazon-s3.mdx

@@ -1,22 +1,134 @@
 # Amazon S3
 
-Amazon S3 is ideal for large or enterprise-grade static JSON APIs.
+Amazon S3 is a solid option for large or enterprise‑grade static JSON APIs, especially when paired with **CloudFront** for global CDN delivery.
 
-**Steps:**
+---
 
-1. Build:
-   ```bash
-   statikapi build
-   ```
+## Using the AWS CLI
 
-2. Sync to S3:
-   ```bash
-   aws s3 sync api-out s3://my-bucket-name/ --content-type "application/json"
-   ```
+### 1) Build locally
 
-3. Enable static website hosting or serve via CloudFront for CDN distribution.
+```bash
+npx statikapi build
+```
+
+### 2) Sync the output to S3
+
+Use `sync` to mirror your local `api-out/` to a bucket. The AWS CLI will generally infer `Content-Type: application/json` for `.json` files. You can also set headers explicitly if needed.
+
+**Basic (let CLI infer content type):**
+
+```bash
+aws s3 sync api-out s3://my-bucket-name/ --delete
+```
+
+**Force JSON content type for everything (only if all files are JSON):**
+
+```bash
+aws s3 sync api-out s3://my-bucket-name/ --delete --content-type "application/json"
+```
+
+**Optional caching headers (tune to your needs):**
+
+```bash
+# Example: short cache to allow quick updates
+aws s3 sync api-out s3://my-bucket-name/   --delete   --cache-control "public,max-age=60"
+```
+
+> If you also upload non‑JSON assets (rare for a pure API), prefer the basic command so the CLI infers the correct `Content-Type` per file.
+
+### 3) Make objects publicly readable
+
+If you need public access, configure a **Bucket Policy** that allows `s3:GetObject` on the objects. Avoid ACLs if Object Ownership is set to “Bucket owner enforced”.
+
+Minimal example policy (adjust `Resource` ARN to your bucket name/region):
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "PublicReadGetObject",
+      "Effect": "Allow",
+      "Principal": "*",
+      "Action": "s3:GetObject",
+      "Resource": "arn:aws:s3:::my-bucket-name/*"
+    }
+  ]
+}
+```
+
+---
+
+## Serving options
+
+### Option A — S3 Static Website Hosting
+
+- Enable **Static website hosting** on the bucket.
+- Access via the website endpoint (varies by region), for example:
+
+```
+http://my-bucket-name.s3-website-us-east-1.amazonaws.com/users/1/index.json
+```
+
+### Option B — CloudFront over S3 (recommended for production)
+
+- Create a **CloudFront distribution** with the S3 bucket as the origin.
+- Set appropriate caching behavior and headers.
+- Access via your CloudFront domain or a custom domain:
+
+```
+https://api.example.com/users/1/index.json
+```
+
+**Direct S3 object URL (when public):**
 
-**Example URL**
 ```
 https://my-bucket-name.s3.amazonaws.com/users/1/index.json
 ```
+
+---
+
+## Automation (CI/CD)
+
+Typical GitHub Actions flow using OIDC and the AWS CLI:
+
+```yaml
+name: Deploy StatikAPI to S3
+on:
+  push:
+    branches: [main]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::123456789012:role/gha-oidc-deploy
+          aws-region: us-east-1
+
+      - name: Install deps
+        run: npm ci
+
+      - name: Build API
+        run: npx statikapi build
+
+      - name: Sync to S3
+        run: aws s3 sync api-out s3://my-bucket-name/ --delete
+```
+
+---
+
+## Considerations
+
+- S3 can scale to very large datasets; pair with **CloudFront** for low‑latency global access and fine‑grained caching.
+- Prefer **short cache** for frequently updated JSON; increase `max-age` for versioned paths.
+- Keep object keys stable if you intend to leverage CDN caching effectively.
+- You can also host your APIs directly with **StatikAPI Cloud** _(coming soon)_ — a managed platform for static JSON hosting with automatic builds and versioned deployments.  
+  [Join the waitlist](#subscription) for early access.

docs/deployments/cloudflare.mdx

@@ -1,70 +1,94 @@
 # Cloudflare Pages & R2
 
-Cloudflare is an excellent choice for hosting small or medium static JSON APIs —  
-especially if you’re already hosting your frontend or documentation there.
+Cloudflare is an excellent choice for hosting small or medium static JSON APIs — 
+especially if you are already hosting your frontend or documentation there.
 
 ---
 
-## ✅ Using Cloudflare Pages
+## Using Cloudflare Pages
 
 You can deploy your `api-out/` folder directly to **Cloudflare Pages**:
 
 ```bash
 npx wrangler pages publish api-out --project-name my-statikapi
 ```
 
-This works great for:
+Cloudflare Pages supports two deployment approaches:
+
+1. **Git Integration** — connect your repository (GitHub, GitLab, or Bitbucket) directly to Cloudflare Pages.  
+   Every time you push changes to your configured branch, Cloudflare will automatically trigger a new build and redeploy your project.
+
+2. **Manual Deployment** — use the `wrangler pages publish` command to upload a local build (as shown above).  
+   This is ideal for projects built by CI/CD pipelines or for static API exports like StatikAPI.
+
+Cloudflare also supports **build hooks and webhooks**, which can trigger rebuilds automatically when your external systems (for example, StatikAPI SaaS or your backend) finish a build.
+
+> Example: You can configure a webhook in Cloudflare Pages and have your StatikAPI build process call it whenever `api-out/` is regenerated.
+
+This approach works great for:
 - Small APIs
 - Public demo endpoints
-- Combined projects (e.g., your docs + JSON API in one Pages site)
+- Combined projects (for example, your documentation and JSON API in one Pages site)
 
-Your JSON files will be served from the same CDN edge network that powers Pages.
+Your JSON files will be served from the same global CDN edge network that powers Cloudflare Pages.
 
-> **Example URL**
-> ```
-> https://my-statikapi.pages.dev/api/users/1/index.json
-> ```
+**Example URL**
+```
+https://my-statikapi.pages.dev/api/users/1/index.json
+```
 
 ---
 
-## ⚠️ Fair Usage Policy
+## Fair Usage Policy
 
 Cloudflare Pages is primarily designed for **websites**, not large API systems.  
 If you plan to serve thousands of JSON files or expect high traffic, review their **fair use policy** and bandwidth limits.
 
-**In short:**
-- Occasional JSON requests are fine ✅  
-- API-like workloads with heavy access may be rate-limited or blocked ❌  
-- Pages cache and limits vary per plan — always check the [Cloudflare Pages Terms of Service](https://developers.cloudflare.com/pages/platform/limits/) and related usage rules.
+**Summary:**
+- Occasional JSON requests are fine.
+- Heavy API-like workloads may be rate-limited or blocked.
+- Limits and caching behavior vary per plan — always review the [Cloudflare Pages Limits](https://developers.cloudflare.com/pages/platform/limits/) and Terms of Service.
 
 ---
 
-## 💡 For Larger Projects — Use R2
+## For Larger Projects — Use R2
+
+If your StatikAPI project produces many JSON files or large objects, consider hosting them in **Cloudflare R2**.
 
-If your StatikAPI project produces **many JSON files** or large objects, host them in **Cloudflare R2**:
+R2 is Cloudflare’s object storage service, similar to AWS S3, designed for large data sets and high availability.
 
-1. Upload the entire `api-out/` folder to R2:
-   ```bash
-   npx wrangler r2 object put my-bucket --file api-out
-   ```
+### Upload to R2
 
-2. Configure public access or route it via a Worker:
-   ```js
-   export default {
-     async fetch(request) {
-       // Proxy JSON files from R2
-     }
-   };
-   ```
+You can upload your entire `api-out/` directory:
 
-R2 gives you:
-- Better scalability and cost control
-- API-friendly object storage
-- Freedom from Pages file limits
+```bash
+npx wrangler r2 object put my-bucket --file api-out
+```
+
+### Serve from R2 or via Workers
+
+You can make your R2 bucket public or serve it behind a Worker:
+
+```js
+export default {
+  async fetch(request) {
+    // Example: Proxy JSON files from R2
+  }
+};
+```
+
+**Advantages of R2**
+- Handles large-scale APIs efficiently
+- No egress bandwidth fees within Cloudflare
+- Can integrate seamlessly with Workers and KV
+- Supports advanced routing and caching
 
 ---
 
-> **Best practice:**  
-> - For small JSON sets or static sites → Pages ✅  
-> - For large datasets or API-style serving → R2 💪  
-> - Always follow Cloudflare’s latest policies and ToS.
+## Considerations
+
+- For **small projects** or when combining with an existing site → use **Cloudflare Pages**
+- For **large datasets** or when serving JSON like an API → use **Cloudflare R2**
+- Always follow Cloudflare’s current **usage policies and terms** to stay within fair-use limits
+- You can also host your APIs directly with **StatikAPI Cloud** *(coming soon)* — a managed hosting solution built for static JSON APIs, automatic builds, and versioned deployments.  
+  [Join the waitlist](#subscription) to get early access.

docs/deployments/github-pages.mdx

@@ -1,20 +1,69 @@
 # GitHub Pages
 
-GitHub Pages can serve JSON just like HTML.
+GitHub Pages can serve JSON files just like regular static assets.
 
-1. Commit your `api-out/` directory.
-2. Push it to a `gh-pages` branch (or `/docs` folder).
-3. Enable Pages in repo settings.
+---
+
+## Manual Deployment
+
+You can manually commit and push your `api-out/` directory to a branch or folder used by GitHub Pages.
 
 ```bash
 git add api-out
 git commit -m "Add API output"
 git subtree push --prefix api-out origin gh-pages
 ```
 
-Your endpoints will be accessible at:
+Your endpoints will be publicly accessible at:
+
 ```
 https://username.github.io/repo-name/users/1/index.json
 ```
 
-> For automation, use GitHub Actions to build and push after every commit.
+---
+
+## Git Integration
+
+GitHub Pages automatically builds and serves content from specific branches (`gh-pages`, `main`, or `docs/` folders depending on settings).  
+Once your repository is configured for Pages, any push to the target branch will trigger an automatic redeploy of your static JSON API.
+
+---
+
+## Automation with GitHub Actions
+
+You can automate your StatikAPI build and deployment using **GitHub Actions**.
+
+Example workflow snippet:
+
+```yaml
+name: Deploy StatikAPI
+on:
+  push:
+    branches: [main]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install dependencies
+        run: npm ci
+      - name: Build API
+        run: npx statikapi build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./api-out
+```
+
+This workflow ensures that every commit to `main` automatically rebuilds and deploys your JSON endpoints to GitHub Pages.
+
+---
+
+## Considerations
+
+- Best for **small APIs**, demos, and documentation datasets.
+- GitHub Pages has limited bandwidth and file size per repository.
+- For **larger or dynamic datasets**, consider using **Cloudflare R2**, **Amazon S3**, or another CDN-backed object storage.
+- You can also host your APIs directly with **StatikAPI Cloud** _(coming soon)_ — a managed hosting platform with automatic builds, caching, and versioned JSON hosting.  
+  [Join the waitlist](#subscription) for early access.