Skip to main content

​
Overview

Tesslate Studio offers three ways to create a project, each suited to different starting points:

Template

Blank React + Vite starter for building from scratch

Git Import

Import from GitHub, GitLab, or Bitbucket

Base

Pre-built template from the Marketplace
All three methods follow the same pattern: you submit a creation request, the server runs a background task to set up the project, and the frontend polls for completion before navigating you to the builder.

​
Method 1: From Template

The template method gives you a clean React + Vite + TypeScript starter project. This is the best option when you want to start from scratch and let AI agents build out the features.
1

Open the Dashboard

Navigate to the Dashboard and click Create New Project.
2

Select Template

Choose Template as your project source.
3

Name Your Project

Enter a descriptive name (for example, “My Landing Page”). Tesslate generates a unique slug automatically, such as my-landing-page-k3x8n2.
4

Set Project Phase

Choose an organizational label:
  • Idea: Planning stage
  • Build: Active development
  • Launch: Ready for production
5

Create

Click Create Project. A background task initializes the project, which typically takes 10 to 15 seconds.

​
What You Get

The template includes a minimal, working React application:
  • React 18 with TypeScript
  • Vite for fast development and Hot Module Replacement (HMR)
  • Tailwind CSS pre-configured
  • A basic App.tsx component ready to customize
  • Development server configured to start automatically

​
API Details

The frontend sends: 
POST /api/projects/
{
  "name": "My Landing Page",
  "source_type": "template"
}
The server responds with a task_id. The frontend uses tasksApi.pollUntilComplete(task_id) to wait for setup, then navigates to /project/{slug}/builder.

​
Method 2: From Git Repository

Import an existing repository from GitHub, GitLab, or Bitbucket. Tesslate clones the repository into a new project container and starts the dev server.
1

Connect Your Provider

If you have not connected a Git provider, click Connect GitHub (or GitLab, or Bitbucket) and complete the OAuth authorization flow.
2

Select Import Source

In the Create Project dialog, choose GitHub, GitLab, or Bitbucket as your project source.
3

Choose a Repository

Browse your repositories or search by name. For organizations you belong to, you can filter by organization.
4

Configure Import

Set the project name and phase. Tesslate auto-detects the branch and framework where possible.
5

Import

Click Import. The server clones the repository and starts the dev server. This may take longer than template projects, depending on the repository size and dependency count.

​
Multi-Provider Support

Tesslate supports three Git providers through a unified API:
ProviderClone URL FormatOAuth Flow
GitHubhttps://github.com/user/repoGitHub OAuth App
GitLabhttps://gitlab.com/user/repoGitLab OAuth App
Bitbuckethttps://bitbucket.org/user/repoBitbucket OAuth App
The backend automatically detects the provider from the URL and uses the appropriate credentials for cloning.

​
API Details

POST /api/projects/
{
  "name": "My Existing App",
  "source_type": "github",
  "git_repo_url": "https://github.com/user/repo"
}
For GitLab and Bitbucket, the source_type value changes to "gitlab" or "bitbucket" respectively.

​
Supported Project Types

  • Create React App
  • Vite + React
  • Next.js (all modes)
  • React + TypeScript
For non-Node.js projects, adding a TESSLATE.md file to the repository root helps Tesslate detect the correct startup command and port. Without this file, the platform defaults to npm install && npm run dev on port 3000.

​
Method 3: From Base

Bases are marketplace templates backed by Git repositories. This is the fastest way to start with a fully-configured project that includes a specific tech stack and working features.
1

Install a Base

If you have not already, browse the Marketplace and install the base you want to use. It will appear in your Library.
2

Create New Project

On the Dashboard, click Create New Project and select Base as the source.
3

Choose Your Base

Pick from your installed bases. Each card shows the tech stack, category, and feature list.
4

Name and Create

Enter a project name and click Create. The server clones the base repository and starts the dev server.

​
API Details

POST /api/projects/
{
  "name": "My SaaS Dashboard",
  "source_type": "base",
  "base_id": "<base-uuid>"
}
  • Vite + React + FastAPI: React frontend with Python API backend and PostgreSQL
  • Next.js 16: Server-side rendering, API routes, and database integration
  • Vite + React + Go: React frontend with a Go API backend
  • React + Tailwind + shadcn/ui
  • Vue 3 + Vite
  • Svelte + SvelteKit
  • Astro for content-heavy sites
  • FastAPI with SQLAlchemy and Alembic
  • Django with REST framework
  • Go with Gin or Fiber
  • Rust with Actix Web
  • Expo (React Native) starter
  • Flutter cross-platform template

​
What Happens After Creation

Regardless of which method you use, the same initialization process runs:
1

Background Task Starts

The server creates a background task that sets up the project infrastructure.
2

Project Directory Created

Files are either generated (template), cloned (Git import), or cloned from the base repository.
3

Container Configuration Generated

Docker mode: A docker-compose.yml file is generated with the appropriate image, ports, volumes, and Traefik labels.Kubernetes mode: A namespace is created (proj-{uuid}), along with a PVC for storage, a file-manager deployment, and service/ingress resources.
4

Dev Server Starts

Dependencies are installed (typically npm install) and the development server launches. The container monitors health via startup probes.
5

Frontend Navigates to Builder

Once the task polling reports completion, the frontend navigates to /project/{slug}/builder where you can start coding.

​
Task Polling

The frontend polls the backend to check on the project setup progress: 
const { task_id } = await projectsApi.create({ name, source_type, ... });
const result = await tasksApi.pollUntilComplete(task_id);
// result.slug contains the project slug for navigation
This pattern ensures a non-blocking user experience. The UI shows a progress indicator while the container initializes in the background.

​
Agent-Assisted Startup

Community bases (external repositories without a TESSLATE.md file) sometimes fail the default startup command. When this happens:
  1. The health check times out after approximately 120 seconds
  2. The UI shows a “Container needs setup” message
  3. An “Ask Agent to start it” button appears
  4. Clicking the button prefills the chat with: “Use the running tmux process to get this up and running. The port for the preview url is .”
  5. The AI agent reads the project files, determines the correct startup command, and runs it
This process works because the container stays alive even when the dev server is not running. In Kubernetes mode, startup probes check for a tmux session (not an HTTP response), so the container remains available for the agent to configure.

​
Troubleshooting

Cause: The background task is still running, or it failed silently.What to try:
  • Wait up to 60 seconds (first-time initialization can be slow, especially for large repositories)
  • Check your internet connection (Git cloning requires network access)
  • Refresh the page and check if the project appears on your Dashboard
  • If the project shows up but the container is not running, try starting it manually from the project settings
Cause: The repository URL is invalid, private without proper credentials, or the provider OAuth token has expired.What to try:
  • Verify the repository is accessible (public, or you have been granted access)
  • Re-authorize your Git provider connection in Settings
  • Confirm the repository contains a valid project (for example, a package.json for Node.js projects)
Cause: The dev server failed to start, or the health check has not completed yet.What to try:
  • Wait 30 to 60 seconds for the initial build
  • Check the container status in project settings
  • If the container status shows “failed,” try restarting it
  • For community bases, use the “Ask Agent to start it” feature to let the AI configure the correct startup command
Cause: The base or imported project uses a different port or startup command than the default.What to try:
  • Add a TESSLATE.md file to the project root specifying the correct port and startup command
  • Use the agent-assisted startup feature to have the AI detect and run the correct command
  • Manually configure the port in the container settings

​
Best Practices

Choose the Right Source

  • Template: When starting from scratch
  • Git Import: When you have existing code
  • Base: When you want a working starter with a specific tech stack

Name Projects Clearly

Use descriptive names that reflect the application’s purpose. Avoid special characters. The auto-generated slug will be URL-safe.

Add TESSLATE.md

For repositories that use non-standard startup commands or ports, include a TESSLATE.md file. This ensures reliable automatic startup for you and anyone who forks your project.

Plan Before Building

Know your tech stack requirements before choosing a creation method. If you need a full-stack project with a database, pick a base that includes those services rather than adding them manually later.

​
Next Steps

Code Editor

Start writing and editing code in your new project

Chat Interface

Use AI agents to build features

Live Preview

See your application running in real time

Git Integration

Connect your project to a Git repository