Documentation Index
Fetch the complete documentation index at: https://mintlify.com/21st-dev/1code/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The Projects router manages project folders, git repository information, and project metadata. Each project represents a local directory that can contain git repositories.
Methods
list
List all projects ordered by most recently updated.
const projects = await trpc.projects.list.query();
Project[]
Unique project identifier
Project name (folder name by default)
Absolute path to project directory
Git remote URL (if repository)
Git provider: github, gitlab, bitbucket
Repository owner (GitHub username or org)
Path to custom project icon
Project creation timestamp
get
Get a single project by ID.
const project = await trpc.projects.get.query({ id: 'proj_123' });
Project | null
create
Create a project from a known path.
const project = await trpc.projects.create.mutate({
path: '/Users/username/projects/my-app',
name: 'My App' // optional
});
Absolute path to project directory
Custom project name (defaults to folder name)
Project
If a project with the same path already exists, the existing project is returned.
openFolder
Open a native folder picker dialog and create a project from the selected folder.
const project = await trpc.projects.openFolder.mutate();
Project | null (null if user cancels)
rename
Rename a project.
const project = await trpc.projects.rename.mutate({
id: 'proj_123',
name: 'New Name'
});
New project name (min 1 character)
Project
delete
Delete a project and all its chats.
const deleted = await trpc.projects.delete.mutate({
id: 'proj_123'
});
Project (deleted project)
This only deletes the project record and associated chats from the database. The actual project folder is not deleted from disk.
refreshGitInfo
Refresh git remote information for a project.
const project = await trpc.projects.refreshGitInfo.mutate({
id: 'proj_123'
});
Project | null
cloneFromGitHub
Clone a GitHub repository and create a project.
const project = await trpc.projects.cloneFromGitHub.mutate({
repoUrl: 'https://github.com/owner/repo'
});
GitHub repository URL (HTTPS, SSH, or short format owner/repo)
Project
Repositories are cloned to ~/.21st/repos/{owner}/{repo}.
locateAndAddProject
Open a folder picker to locate an existing clone of a specific repository.
const result = await trpc.projects.locateAndAddProject.mutate({
expectedOwner: 'facebook',
expectedRepo: 'react'
});
if (result.success) {
console.log('Project added:', result.project);
} else {
console.log('Failed:', result.reason);
}
Expected repository owner
| { success: true; project: Project }
| { success: false; reason: 'no-window' | 'canceled' | 'wrong-repo'; found?: string }
pickCloneDestination
Open a folder picker to choose where to clone a repository.
const result = await trpc.projects.pickCloneDestination.mutate({
suggestedName: 'react'
});
if (result.success) {
console.log('Clone to:', result.targetPath);
}
Suggested folder name for the clone
| { success: true; targetPath: string }
| { success: false; reason: 'no-window' | 'canceled' }
uploadIcon
Upload a custom icon for a project.
const project = await trpc.projects.uploadIcon.mutate({
id: 'proj_123'
});
Project | null
removeIcon
Remove the custom icon for a project.
const project = await trpc.projects.removeIcon.mutate({
id: 'proj_123'
});
Project
getLaunchDirectory
Get the directory passed via CLI when launching the app (consumed once).
const path = await trpc.projects.getLaunchDirectory.query();
if (path) {
console.log('Launched with:', path);
}
string | null
Examples
Create project from path
// Check if directory exists first
const fs = require('fs');
const projectPath = '/Users/username/projects/my-app';
if (fs.existsSync(projectPath)) {
const project = await trpc.projects.create.mutate({
path: projectPath
});
console.log('Project created:', project.id);
}
Clone and open GitHub repo
try {
const project = await trpc.projects.cloneFromGitHub.mutate({
repoUrl: 'https://github.com/vercel/next.js'
});
console.log('Cloned to:', project.path);
console.log('Remote:', project.gitRemoteUrl);
} catch (error) {
console.error('Clone failed:', error.message);
}
List projects with git info
const projects = await trpc.projects.list.query();
for (const project of projects) {
console.log(`${project.name} (${project.path})`);
if (project.gitRemoteUrl) {
console.log(` Git: ${project.gitOwner}/${project.gitRepo}`);
}
}