Skip to content

README.md

Latest commit

 

History

History
86 lines (57 loc) · 3.61 KB

README.md

File metadata and controls

86 lines (57 loc) · 3.61 KB
Raw

telescope-web

The web application for telescopetest.io — upload and view @cloudflare/telescope test results in an interactive UI. Built with Astro and hosted on Cloudflare Workers.

Part of the cloudflare/telescope monorepo. Lives at packages/telescope-web/.

Stack

  • Astro v6 with @astrojs/cloudflare adapter
  • Cloudflare Workers (D1, R2, AI bindings)
  • Prisma v7 with @prisma/adapter-d1 for D1 (SQLite)
  • React v19 for interactive components
  • Node.js 24+ required

Project Setup

To set up for local development, install dependencies and run the one-time setup script from packages/telescope-web/:

cd packages/telescope-web
npm install

Then initialize a few things:

  • create local database (will prompt you to confirm that you want to perform the DB migrations)
  • generate Prisma client (in generated/prisma folder)
  • create R2 bucket (might prompt you to log into your Cloudflare account)
  • generate TypeScript types to match wrangler configuration (worker-configuration.d.ts)

To accomplish all that, you can simply run:

npm run dev:setup

You should now be able to use the application and run npm run studio to view local D1 data in Prisma Studio and create migrations.

Running Locally

Run npm run dev to view the site with Astro's hot reload (instantly reflect changes) using the adapter for Cloudflare.

DB Migrations

We use Prisma to generate SQL for migrations, and Wrangler to apply them. Prisma migrate does not fully support D1 yet, so you cannot follow the default prisma migrate workflows. Instead, migration need to be done as follows:

Normal Use

  1. Make your edits to prisma/schema.prisma.
  2. Run npx wrangler d1 migrations create telescope-db-development {{describe_changes_here}} --env development. This should create an empty SQLite file with a comment at the top.
  3. Run
npx prisma migrate diff \
  --from-config-datasource \
  --to-schema ./prisma/schema.prisma \
  --script \
  --output migrations/{{file_created_by_previous_step}}.sql

This should fill your created file with the raw SQLite for your changes.

  1. Run npm run generate to regenerate a Prisma Client that reflects your new changes in schema.prisma.
  2. Run npm run migrate:development to apply this new migration to your local database.

Note about Workers AI (AI content review)

One thing to note is that telescope-web uses Workers AI for AI content review on uploads. Workers AI always uses tokens that can incur costs, even in local/remote testing. AI content review is disabled locally by default. You can optionally enable AI content review (which may start costing money) by running the command cp .dev.vars.example .dev.vars and setting ENABLE_AI_RATING=true.

Testing in Staging

Staging allows you to test changes in a remote environment that isn't production. To deploy to staging, run npm run deploy:staging. This command will only work if you have permission to deploy to telescope-web's remote Worker.

Deployment to Production

Changes to the production website should only be deployed on Cloudflare workers on successful PR into @cloudflare/telescope. To run this deployment, we have a GitHub workflow .github/workflows/deploy.yml. This is what that workflow does:

  1. Checks out code
  2. Installs Node.js 24
  3. Installs project dependencies
  4. Applies any new D1 migrations
  5. Generates Prisma client
  6. Builds project (generates dist/)
  7. Deploys project (uploads dist/ to Cloudflare)

Once successful, the deployed site can be found on telescopetest.io.