Blank Files Website

Laravel application that powers blankfiles.com. Browse and download minimal valid blank files by type and category. File data and assets are served from the filearchitect/blank-files repository via a configurable CDN.

Requirements

• PHP 8.2+
• Composer
• Node.js 18+ (for Vite frontend build)

Installation

git clone https://github.com/filearchitect/blankfiles-website.git
cd blankfiles-website
composer install
cp .env.example .env
php artisan key:generate

Set CDN_URL in .env (see Configuration). Then build the frontend and run the app:

npm install && npm run build
php artisan serve

Or use Laravel Herd with a .test domain.

Configuration

Variable	Description
CDN_URL	Required. Base URL used to construct downloadable file URLs as {CDN_URL}/files/{filename}. Default: https://raw.githubusercontent.com/filearchitect/blank-files/main (set in config/app.php).
CATALOG_URL	Optional. Direct URL for the catalog JSON (files/files.json). Default is https://raw.githubusercontent.com/filearchitect/blank-files/main/files/files.json for freshness.
CACHE_ENABLED	Optional. When true, the file list from the CDN is cached. TTL is controlled by CATALOG_TTL_MINUTES (default 10). See config/cache.php and app/Services/FileService.php.
CATALOG_TTL_MINUTES	Optional. Cache TTL in minutes for the remote catalog when CACHE_ENABLED=true. Lower values reflect new formats sooner; higher values reduce CDN fetches.
API_KEYS	Optional. Comma-separated API keys for higher-rate API clients (used by X-API-Key or Authorization: Bearer ...).
API_PUBLIC_RATE_LIMIT	Optional. Public API requests/minute limit (default 30).
API_KEY_RATE_LIMIT	Optional. API-key requests/minute limit (default 300).
API_USAGE_LOG_CHANNEL	Optional. Logging channel for API usage analytics (default api_usage).
OPENPANEL_CLIENT_ID	Optional. Enables OpenPanel web analytics script when set.
OPENPANEL_CLIENT_SECRET	Optional. Reserved for server-side OpenPanel events (not exposed to browser script).

Project structure

Path	Purpose
app/Http/Controllers/FileController.php	Web: homepage, file detail page, download proxy.
app/Http/Controllers/Api/FileController.php	API: list all files, list files by type.
app/Services/FileService.php	Fetches catalog JSON (CATALOG_URL) and formats file URLs from CDN_URL.
routes/web.php	Web routes (home, files show, download).
routes/api.php	API v1 routes.
resources/views/files/	Blade views for file listing and file detail.

Deployment

On push to main, GitHub Actions:

1. Builds the frontend (Vite) with npm ci and npm run build.
2. SCPs public/build/ to the Forge server.
3. Triggers a Laravel Forge deployment.
4. Runs php artisan optimize:clear on the server.

Required repository secrets:

• FORGE_SSH_HOST — SSH host for the server.
• FORGE_SSH_USER — SSH user (e.g. forge).
• SSH_PRIVATE_KEY — Private key for SCP/SSH.
• FORGE_SERVER_ID — Forge server ID.
• FORGE_SITE_ID — Forge site ID.
• FORGE_API_KEY — Forge deploy token.

See .github/workflows/deploy.yml.

---

For developers and bots

Base URL

Production: https://blankfiles.com. HTML and JSON are available; use Accept: application/json where applicable.

Web routes

Method	Path	Description
GET	/	Homepage: file list by category. Responds with JSON when Accept: application/json. Throttle: 30/min.
GET	/upload-testing	Binary-focused landing page for upload testing intent, linking to high-demand file formats and categories.
GET	/files/{category}/{type}	SEO-friendly file detail page (e.g. /files/document-spreadsheet/xlsx). Constraints: category, type = [A-Za-z0-9\-]+.
GET	/files/download/{category}/{type}	Download proxy: streams the file with Content-Disposition: attachment (filename blank.{type} or blank.{type}.zip). Throttle: 60/min.

API routes (prefix api/v1)

Method	Path	Response
GET	/api/v1/files	{ "files": [ ... ], "meta": { "version", "generated_at", "count" } }.
GET	/api/v1/files/{type}	Same schema, filtered by extension.
GET	/api/v1/files/{category}/{type}	Same schema with exactly one matching entry when found; 404 when missing.
GET	/api/v1/status	API health + aggregate catalog metrics (file_count, type_count, category_count) and upstream source info.

Machine-friendly notes

• The canonical file catalog schema is defined in the blank-files repo: files/files.json (key files, array of { type, url, category, package? }).
• Download URLs: use the API url field for direct CDN access, or GET /files/download/{category}/{type} for a same-origin download with a predictable filename.
• Conditional requests are supported on API responses and sitemap (ETag, Last-Modified).
• Rate limits: public IP-based limits and optional API-key limits (X-API-Key).
• API usage analytics are logged to storage/logs/api-usage-*.log (configurable channel).
• Compatibility policy: API policy.
• Web landing analytics for growth pages are logged to storage/logs/web-traffic-*.log.

Client snippets

curl -sS "https://blankfiles.com/api/v1/files/document-spreadsheet/xlsx" \
  -H "Accept: application/json" \
  -H "X-API-Key: $BLANKFILES_API_KEY"

const res = await fetch("https://blankfiles.com/api/v1/files", {
  headers: { "Accept": "application/json", "If-None-Match": etag }
});
if (res.status === 304) {
  // unchanged
}

import requests
r = requests.get("https://blankfiles.com/api/v1/status", timeout=20)
r.raise_for_status()
print(r.json())

Compatibility policy

• URL versioning is stable under /api/v1/*.
• Breaking changes require a new major API path version.
• Deprecated endpoints are kept for at least 90 days before removal.
• New fields may be added; clients should ignore unknown fields.

---

Related

• filearchitect/blank-files — Source of truth for the file list and blank file assets.

MCP server (for agent marketplaces/registries)

This repository now includes a minimal MCP server that exposes Blank Files as tool calls.

• Script: scripts/mcp/blankfiles-mcp.mjs
• Run: npm run mcp:server
• Optional env: BLANKFILES_BASE_URL (default: https://blankfiles.com)

Available MCP tools:

• list_blank_files — list files, optional filters (category, type, limit)
• files_by_type — list entries by extension
• file_by_category_type — deterministic single lookup by category + extension

Example local MCP client config entry:

{
  "mcpServers": {
    "blankfiles": {
      "command": "node",
      "args": ["/absolute/path/to/blankfiles-website/scripts/mcp/blankfiles-mcp.mjs"],
      "env": {
        "BLANKFILES_BASE_URL": "https://blankfiles.com"
      }
    }
  }
}

Registry submission helpers:

• Template metadata: scripts/mcp/registry/server.json.template
• Publish checklist: scripts/mcp/registry/PUBLISHING.md

Published package workspace:

• packages/blankfiles-mcp (publish as @filearchitect/blankfiles-mcp)

OpenClaw skill (ClawHub discoverability)

This repository includes an OpenClaw-ready skill bundle:

• Skill path: skills/blankfiles
• Skill entry: skills/blankfiles/SKILL.md
• Publish guide: skills/blankfiles/references/publish.md

Typical publish flow:

npm i -g clawhub
clawhub login
clawhub publish ./skills/blankfiles \
  --slug blankfiles \
  --name "Blank Files Gateway" \
  --version 1.0.0 \
  --changelog "Initial release" \
  --tags latest

License

This project is licensed under the MIT License.