Skip to content

getting-started.md

Latest commit

 

History

History
82 lines (62 loc) · 3.82 KB

getting-started.md

File metadata and controls

82 lines (62 loc) · 3.82 KB
Raw
title Getting started
description Run Uptide on a TypeScript repository in four commands, with nothing installed and no account.

Getting started

For someone running Uptide for the first time: what to run, in what order, and what the repository needs.

Requirements

  • Node 20 or newer.
  • A TypeScript repository, or JavaScript the compiler can see (allowJs), with a lockfile.
  • A package manager Uptide supports: check works on npm, pnpm (workspaces and catalogs), Yarn classic and bun (text lockfile); fix works on npm (lockfile v2/v3), pnpm, and Yarn classic/Berry with the node-modules linker. Yarn Plug'n'Play, bun's binary lockfile and Deno are not supported (troubleshooting).
  • Installed dependencies for check and fix (list needs none).

No account, no config file, no API key for anything but assisted fixes.

The four commands

In your repository:

npx uptide list                            # fast discovery; no install or compilation
npx uptide check zod                       # analyze one or more named dependencies (install first)
npx uptide fix zod                         # migrate on a new branch, verified; nothing is pushed
npx uptide pr --branch uptide/zod-4.6.5    # prints the plan; add --yes to push and open the PR

npx uptide with no command shows where zod and stripe stand in the repository: installed, latest, majors behind.

  1. list reads manifests, lockfiles, source imports and registry metadata, and says what to upgrade first and why. It compiles nothing and installs nothing. Details.
  2. check <package> compiles your code against the target version and reports what breaks, where, and who can fix it (a rule, the agent, or you). Breaking means the compiler, the runtime probe or a migration pack confirmed it (concepts). Details.
  3. fix <package> upgrades one dependency on a new branch in a temporary clone, migrates the code, and verifies with your TypeScript and your tests. Nothing is pushed. Details.
  4. pr pushes a finished branch and opens its pull request with the stored report, only with --yes. Details.

Between check and fix, plan gives the order to upgrade several dependencies in (details).

A real run

fixtures/repos/storefront is a small pnpm workspace in the Uptide repository, written to exercise it: two packages on zod 3 and stripe 14, with a few tests. The README shows its check zod and fix zod output; the check and fix pages show stripe. Everything in those samples is real output from that fixture.

The one type error left after each fix run is the fixture's own, there on purpose: errors a repository already had are subtracted, never blamed on the upgrade.

Assisted fixes

Sites no rule covers go to the Claude Agent SDK, with your own ANTHROPIC_API_KEY. fix runs only with the SDK: the first run downloads it once (about 300 MB, asking first in a terminal), and without the key or the SDK it stops before any clone (fix). Which model, and what it costs: models. What is sent: privacy.

What gets installed

npx uptide runs the published uptide package. It is one bundle: it inlines its dependencies. The notice for every package in that bundle, with the full text of its license, ships in the npm package as THIRD-PARTY-NOTICES and is generated from the bundle itself at build time. Releases up to and including 0.3.0 were published under the MIT license; 0.4.0 and later are Apache-2.0.

In CI

npx uptide init writes a workflow that runs the Uptide Action on a schedule in your own GitHub Actions and opens draft pull requests with verified migrations: CI.