Skip to content

Latest commit

 

History

History
162 lines (122 loc) · 6.16 KB

README.md

File metadata and controls

162 lines (122 loc) · 6.16 KB

SEO Auditor (TypeScript)

A website SEO analysis tool demonstrating Render Workflows for distributed task execution.

Enter a URL and the app crawls your site, spawning parallel analysis tasks across multiple instances to check:

  • Meta tags: Title, description, Open Graph tags
  • Broken links: HTTP status validation
  • Heading structure: H1-H6 hierarchy
  • Image accessibility: Alt text presence
  • Performance: Page size, load time, resource count

Architecture

┌─────────────────┐         ┌──────────────────────────────────────┐
│   API Service   │         │          Workflow Service            │
│   (Express)     │         │                                      │
│                 │         │                                      │
│  Frontend ────────────────▶ audit_site task                      │
│                 │  SDK    │      │                               │
│  Results    ◀─────────────│      ▼                               │
│                 │         │  crawl_pages task                    │
└─────────────────┘         │      │                               │
                            │      ▼                               │
                            │  ┌───────────────────────────────┐   │
                            │  │ analyze_page  analyze_page    │   │
                            │  │ analyze_page  analyze_page    │   │
                            │  │     ... (parallel tasks)      │   │
                            │  └───────────────────────────────┘   │
                            └──────────────────────────────────────┘

Prerequisites

  • A Render account with Workflows access (request at render.com/workflows)
  • A Render API key
  • Node.js 20+

Deployment

1. Create the workflow service

Workflows are created via the Render Dashboard (not render.yaml during early access):

  1. Go to the Render Dashboard
  2. Select New > Workflow
  3. Connect your repository containing this code
  4. Configure:
    • Name: seo-audit-workflow-ts
    • Root Directory: typescript
    • Build Command: npm install && npm run build
    • Start Command: node dist/workflows/index.js
  5. Deploy the workflow

2. Deploy the API service

Use the included render.yaml blueprint:

  1. Go to the Render Dashboard
  2. Select New > Blueprint
  3. Connect this repository
  4. Configure environment variables:
    • RENDER_API_KEY: Your Render API key
    • WORKFLOW_SLUG: The slug of your workflow (e.g., seo-audit-workflow-ts)
    • WORKFLOW_ID: The workflow ID (e.g., wfl-xxxxx) for task discovery in the UI

Or deploy manually:

  1. Select New > Web Service
  2. Connect your repository
  3. Configure:
    • Name: seo-audit-api-ts
    • Runtime: Node
    • Build Command: npm install && npm run build
    • Start Command: node dist/api/index.js
  4. Add the environment variables listed above

3. Deploy the frontend

See the main README for frontend deployment instructions. The frontend is shared between Python and TypeScript backends.

Local development

  1. Install dependencies:

    npm install

  2. Build the project:

    npm run build

  3. Set environment variables:

    export RENDER_API_KEY=your-api-key
export RENDER_USE_LOCAL_DEV=true
export WORKFLOW_SLUG=seo-audit-workflow-ts
export WORKFLOW_ID=wfl-xxxxx

  4. Start the local task server (in one terminal):

    render workflows dev -- node dist/workflows/index.js

  5. Run the API service (in another terminal):

    npm run dev

For more details, see the Workflows local development guide.

Project structure

├── workflows/
│   ├── index.ts          # Workflow task definitions
│   └── analyzers.ts      # SEO analysis functions
├── api/
│   └── index.ts          # Express API
├── package.json
├── tsconfig.json
├── render.yaml           # Blueprint for API service
└── README.md

How it works

  1. User submits a URL via the frontend
  2. API service triggers the audit_site workflow task using @renderinc/sdk
  3. audit_site calls crawl_pages to discover pages (sitemap or link crawling)
  4. For each discovered page, audit_site spawns an analyze_page task
  5. Each analyze_page runs independently on its own instance
  6. Results are aggregated and returned to the frontend

This demonstrates Workflows' key capability: distributing work across many instances with automatic orchestration, retries, and observability.

API endpoints

Method Endpoint Description
GET / Health check
POST /audit Start an audit (body: {"url": "...", "max_pages": 25})
GET /audit/:id Get audit status and results
GET /health Health check

TypeScript SDK

This demo uses the official @renderinc/sdk package which provides:

  • Task Definition: Register tasks with task() function
  • REST API Client: Run and monitor tasks with Render client
  • Type Safety: Full TypeScript support with IntelliSense
  • Retry Logic: Configurable retry behavior for tasks
  • Task Spawning: Execute tasks from within other tasks