Set Up the Starter App

The starter is the completed Project Planner from the previous chapter, with all the “task” terminology replaced by “issue” and the app renamed to Issue Tracker. Before we start adding auth, let’s get it running and look at what is already there.

Install Dependencies

pnpm install

Create a Convex Project

The starter has a convex/ directory with the schema, queries, mutations, cron job, and seed script from the previous chapter. It is not connected to a Convex deployment yet. You need to create a new one.

In a terminal, run:

npx convex dev

When prompted:

  • Choose to create a new project (not link to an existing one)
  • Give it a name like issue-tracker
  • Choose cloud deployment over local deployment (BETA)
  • Say no to any AI-related features Convex offers to install

Once setup completes, npx convex dev stays running. It watches your convex/ directory and pushes changes to your development backend automatically. Stop the process with Ctrl+C.

Run the Frontend

In a second terminal, start Vite:

pnpm dev

Open that URL in your browser. You should see an empty Issue Tracker, the same UI you finished the previous chapter with, without the data you had in your old Convex project.

Seed Some Sample Data

The starter carries over the Faker-based seed script from the previous chapter. Run it now so we have something to look at:

pnpm run seed

Refresh the browser. 50 projects should appear on the list page. Click into any one of them and you will see the same kanban board with issues in the three columns. Create a new project, drag an issue between columns, delete one. Everything works. The behavior of the app has not changed from where we left it in the previous chapter.

A Tour of What is There

Skim these files before we start modifying them. Nothing here should be new to you. The point is to know where things live, so that the rest of the chapter is easier to follow.

Backend (convex/):

  • schema.ts — two tables: projects (with soft-delete via deletedAt and a search_name text index) and issues (linked to a project via projectId, with a by_project index).
  • projects.ts — list (paginated + search), get, create, remove (soft delete), and an internalMutation called deleteProjectCascade that deletes a project’s issues in batches.
  • issues.ts — list, create, updateStatus, remove. Completely open: no auth checks anywhere, anyone can call any of them.
  • cleanup.ts + crons.ts — a daily cron that permanently removes projects that have been soft-deleted for a while.
  • seed.ts + scripts/seed.ts — the Faker-based seed pipeline, with tasks renamed to issues.

Frontend (src/):

  • routes/__root.tsx — the header that says “Issue Tracker” in the top-left.
  • routes/index.tsx — the paginated project list (uses usePaginatedQuery).
  • routes/projects/$projectId.tsx — the project detail page that renders the kanban for a single project.
  • components/kanban-board.tsx, column.tsx, issue-card.tsx — the drag-and-drop kanban, now filtering by projectId.
  • components/create-project-dialog.tsx, delete-project-dialog.tsx, add-issue-dialog.tsx, project-card.tsx, project-search.tsx — the dialogs and cards the list and detail pages use.
  • hooks/use-update-issue-status.ts — the optimistic-update wrapper around api.issues.updateStatus that makes drag-and-drop feel instant.

What We are Adding

Here is the full rule set we will enforce by the end of the chapter:

Reading (no sign-in required)

  • Anyone — signed in or not — can list projects and view the issues inside them.

Writing (sign-in required)

  • Any signed-in user can create a project. They become that project’s owner.
  • Any signed-in user can create an issue on any project. They become that issue’s creator. New issues always start in To Do.
  • The issue’s creator can edit or delete the issue, but only while its status is To Do. Once the issue moves out of To Do, the creator can no longer edit or delete it.
  • The project’s owner can move any issue in their project between columns, regardless of who created it. They are the triager: other people create issues, the owner decides what to work on next.
  • The project’s owner can delete their project. Nobody else can.

On top of that, we will add a profile page where users can edit their display name and upload a custom avatar. That is where we will use Convex’s file-storage API. We will also add an “Import from GitHub” feature for project owners that pulls open issues from a public repo. That is where we will use Convex actions.