What the agent does
The agent reads how the pages set their heads. In an app shaped like nuxt/movies, package.json runs a Nuxt 4 nightly build (nuxt-nightly@4.6.0) with future.compatibilityVersion: 5 in nuxt.config.ts, pins pnpm 11.1.2 and Node 24 under devEngines, and loads @nuxt/image, @nuxtjs/i18n with fourteen locales, @unocss/nuxt, @vueuse/nuxt and @nuxtjs/html-validator. app/app.vue calls useHead with a title template, a site-wide description, an og:image and the twitter card tags. app/pages/[type]/[id].vue validates type as movie or tv, awaits getMedia and getRecommendations in one Promise.all, and calls useHead with the item's name or title, a description from overview and an og:image built with useImage from poster_path. app/pages/person/[id].vue does the same with name, biography and profile_path. No page emits a script tag, so a crawler reading a film page gets a title and a description and nothing structured.
It then reads what the data carries. shared/types.ts declares Media with title or name, overview, release_date or first_air_date, runtime, genres, vote_average and vote_count, production_companies, homepage, external_ids with imdb_id and credits with cast and crew, and Person with name, birthday, place_of_birth, biography, homepage and also_known_as. app/composables/tmdb.ts fetches through fetchTMDB, which keys a useState entry and an LRU cache by a hash of the URL and params and adds the i18n locale as language, so the same page renders in the visitor's language. The agent writes app/composables/jsonld.ts with two builders: a Movie or TVSeries from a Media and its type (name, description, datePublished from release_date or first_air_date, duration from runtime as an ISO 8601 period, genre names, image through the same useImage provider the og:image uses, an aggregateRating from vote_average and vote_count when there are votes, actors from the first cast entries, a director from the crew entry whose job is Director, sameAs from imdb_id and homepage, and inLanguage from the locale), and a Person from a Person. Each page passes its object to useHead as a script entry with type: 'application/ld+json', and the builder escapes < because overviews and biographies are free text from TMDB.
Tests follow the repository's own. app/components/StarsRate.nuxt.test.ts mounts a component with @vue/test-utils under Vitest through @nuxt/test-utils, vitest.config.ts includes every *.test.ts under components and composables, and tests/unit/mocks.ts holds fixtures. The agent adds app/composables/jsonld.nuxt.test.ts that feeds a Media and a Person fixture to the builders and asserts the @type, the duration string, the escaped <, that a show gets TVSeries with first_air_date as datePublished, and that an item with no votes carries no aggregateRating. Then it runs pnpm run test:unit, pnpm run lint with @antfu/eslint-config and pnpm run typecheck with vue-tsc, the three steps in .github/workflows/tests-unit.yml. It also builds with pnpm build, starts .output/server/index.mjs and fetches a film page and a person page with curl to show the script in the server-rendered HTML.
The agent leaves the existing head entries, the i18n setup and the fetch cache alone, and adds no module such as a schema.org integration, because the data is already on the page and the builders are a few dozen lines the unit tests cover. The route rule in nuxt.config.ts that sends cache-control: private, no-store on every path stays as it is.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add structured data to this Nuxt app. Read package.json, nuxt.config.ts, app/app.vue, app/pages/[type]/[id].vue, app/pages/person/[id].vue, app/composables/tmdb.ts, shared/types.ts, vitest.config.ts, app/components/StarsRate.nuxt.test.ts, tests/unit/mocks.ts and .github/workflows/tests-unit.yml first, and note how each page already calls useHead. Add a composable with builders that turn a Media and its type into a Movie or TVSeries object and a Person into a Person object, using name, description, release or first air date, runtime as an ISO 8601 duration, genres, the poster through useImage, an aggregateRating only when there are votes, cast and director from credits, sameAs from imdb_id and homepage, and inLanguage from the i18n locale, escaping < in the serialized JSON. Emit each object from the page's useHead as an application/ld+json script. Add a Vitest file next to the composable in the repository's style covering both builders, the TV case, the no-votes case and the escaping. Run the unit tests, lint and typecheck as the workflow does, build the app, start the server output and fetch a film page and a person page with curl to show the script in the server-rendered HTML, and open a pull request that quotes the test output and the fetched blocks. Do not add modules or change the fetch cache.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request on its own branch that adds app/composables/jsonld.ts and app/composables/jsonld.nuxt.test.ts and changes app/pages/[type]/[id].vue and app/pages/person/[id].vue. package.json, nuxt.config.ts and the i18n files are untouched.
The description quotes the Vitest run with the new file among the component and composable tests, the lint and typecheck results, and the ld+json block as curl fetched it from the built server for one film and one person, so a reviewer sees that the script is in the first response rather than added after hydration.
Before merging, a reviewer decides whether the category and genre list pages should carry an ItemList, whether the rating should be published at all given that TMDB votes are user submissions, and whether the director and cast lists should be capped. Each is a follow-up on the same session, where the build output is still on disk.
Run it on every Nuxt page served without structured data
This is a change to start from the terminal and read later: one POST /o/{org}/sessions with this prompt and the repository in resources. The run reads the heads and the types, writes the builders and the tests, builds the site and reads the markup back before opening the pull request. The sandbox parks with its disk when the turn ends, so add an ItemList to the genre pages as a follow-up wakes it with node_modules and the build in place.
A team with several Nuxt sites sends the same body once per repository, one run each, and each run finds that site's own pages and data shapes. Give the API key a webhook_url and Rush posts run.completed or run.failed with the session_url when each turn ends. Send a request_id with each body so a retried POST returns the run it already started.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The data for a Movie object is already on the page; what takes the time is checking that the object a crawler receives is right in every locale, for shows as well as films, and for an item with no votes or no director. The agent writes those cases as unit tests in the repository's own style and runs them beside the existing ones, so the pull request carries proof instead of a sample.
The record keeps the build and the curl fetches, so a reviewer can see the script in the server-rendered HTML of a real page without checking the branch out. The sandbox parks with the build on disk, and a follow-up such as adding breadcrumbs or an ItemList reuses it rather than starting from a cold install.
Frequently asked questions
Is the script in the server-rendered HTML?
Yes. Both pages await their data in setup before calling useHead, so the head is rendered on the server and the script is in the first response. The curl fetches in the pull request show it.
Does it follow the visitor's language?
Yes. fetchTMDB sends the i18n locale as the language parameter, so the description and genre names come back in that language, and the builder sets inLanguage from the same locale.
Why not a schema.org module?
The builders are a few dozen typed lines against shared/types.ts and the unit tests cover them. A module would add a dependency and its own conventions for little gain here; if you prefer one, a follow-up can swap it in.
What does a TV show get?
A TVSeries with first_air_date as datePublished and the same name, description, genres, image, cast and rating fields as a film, with duration left out when there is no runtime.
Does it change caching or the fetch layer?
No. The builders read the objects the pages already hold. The useState and LRU cache in tmdb.ts and the cache-control route rule stay exactly as they are.
More Nuxt jobs
The same job on other stacks
- Add Structured Data to a Pelican Blog (Pelican)
- Add Structured Data (JSON-LD) to a SvelteKit App (SvelteKit)
- Add Structured Data to a VitePress Blog (VitePress)