Skip to main content

​
Get started with Polaris

This guide will take you from zero to creating your first AI-powered project in Polaris IDE.
1

Sign up for Polaris

Visit Polaris IDE and create your account using Stack Auth.
# Sign in with your GitHub account
# Grants access to import/export repositories
Free tier includes:
  • 10 projects
  • AI code suggestions
  • Real-time collaboration
  • WebContainer execution
2

Create your first project

From the projects dashboard, click “New Project” or use the keyboard shortcut Cmd+N (Mac) / Ctrl+N (Windows).You can create a project in three ways:Option 1: Start from scratch
# Click "New Project"
# Give it a name like "my-first-app"
# Click "Create"
Option 2: Import from GitHub
# Click "Import from GitHub"
# Authenticate with GitHub OAuth
# Select a repository
# Polaris will clone all files automatically
Option 3: AI-generated project (Pro feature)
# Click "Generate with AI"
# Describe your project: "A todo app with React and TypeScript"
# AI creates complete project structure
Project names are automatically generated using the unique-names-generator package, but you can customize them.
3

Add files to your project

Once inside your project, use the file explorer to create files and folders.Create a new file:
  • Right-click in the file explorer
  • Select “New File”
  • Name it index.html
  • Press Enter
Create a folder:
  • Right-click in the file explorer
  • Select “New Folder”
  • Name it src
  • Press Enter
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My First Polaris App</title>
</head>
<body>
  <h1>Hello from Polaris!</h1>
  <script src="src/app.js"></script>
</body>
</html>
Files auto-save after 1500ms of inactivity. You’ll see a loading indicator while saving.
4

Use AI code suggestions

Start typing in your editor and watch AI suggestions appear as ghost text.How it works:
  1. Type code naturally in the editor
  2. After 300ms, Polaris sends context to the AI:
    • Current line
    • 5 lines before cursor
    • 5 lines after cursor
    • File name and extension
  3. AI suggestion appears as gray text
  4. Press Tab to accept the suggestion
Example workflow:
// Type this:
function calculateTotal(items) {
  // AI suggests:
  // return items.reduce((sum, item) => sum + item.price, 0);
}
Suggestions are powered by Moonshot AI Kimi K2.5 via OpenRouter (primary) or Cerebras GLM-4.7 as a fallback.
5

Try Quick Edit (Cmd+K)

Quick Edit lets you transform code using natural language.Steps:
  1. Select code you want to change
  2. Press Cmd+K (Mac) or Ctrl+K (Windows)
  3. A tooltip appears with an input field
  4. Describe your change: “add error handling”
  5. Press Enter or click “Submit”
  6. AI refactors your code instantly
Example:
Before
const data = await fetch('/api/users');
const users = await data.json();
After Quick Edit with “add error handling and loading state”:
After
try {
  const data = await fetch('/api/users');
  if (!data.ok) {
    throw new Error(`HTTP error! status: ${data.status}`);
  }
  const users = await data.json();
} catch (error) {
  console.error('Failed to fetch users:', error);
}
Quick Edit only works when text is selected. If no text is selected, Cmd+K does nothing.
6

Chat with AI about your code

Open the conversation sidebar to ask questions about your project.Click the chat icon in the sidebar or use the keyboard shortcut.Example prompts:
  • “Where is the authentication logic?”
  • “Explain this function to me”
  • “How do I add a new route?”
  • “Find all usages of this variable”
  • “Generate unit tests for this component”
How it works:
// Conversations are stored in Convex
// Each message has a role: "user" or "assistant"
// Status can be: "processing", "completed", "cancelled", "failed"
The AI assistant has access to:
  • Your entire project file tree
  • File contents
  • Recent changes
  • Conversation history
Conversations are saved per-project and persist across sessions. You can start multiple conversations for different topics.
7

Run your code (WebContainer)

Polaris includes in-browser code execution via WebContainer.Steps:
  1. Click the Terminal icon in the bottom panel
  2. Run commands like you would locally:
npm install
npm run dev
  1. Click Preview to see your app running
Example workflow:
Terminal
$ npm init -y
$ npm install react react-dom
$ npm run build
# Preview opens in split pane
WebContainer runs a real Node.js environment in your browser. Most npm packages work out of the box.
8

Export to GitHub

When you’re ready to deploy, export your project to GitHub.Steps:
  1. Click the GitHub icon in the top navigation
  2. Select “Export to GitHub”
  3. Authenticate with GitHub OAuth (if not already)
  4. Enter repository details:
    • Repository name
    • Description
    • Public or Private
  5. Click “Export”
  6. Polaris creates a new repository and pushes all files
# Polaris creates a commit with all project files
# Push is non-forced, preserving history
GitHub export requires a valid GitHub OAuth token. Make sure you’ve connected your GitHub account in settings.

​
Keyboard shortcuts

Speed up your workflow with these shortcuts:
ActionMacWindows
New projectCmd+NCtrl+N
Quick EditCmd+KCtrl+K
Accept suggestionTabTab
Toggle sidebarCmd+BCtrl+B
Command paletteCmd+PCtrl+P
Save fileAuto-save after 1500msAuto-save after 1500ms

​
Next steps

Install locally

Set up Polaris for local development

Editor features

Learn advanced editor capabilities

AI features

Master AI-powered coding

API reference

Integrate Polaris into your tools

​
Troubleshooting

Possible causes:
  • Check your internet connection
  • Verify API keys are configured (for self-hosted)
  • Wait at least 300ms after typing (debounce delay)
  • Ensure file has valid content (not empty)
Solution:
# Check browser console for errors
# Look for fetch failures to /api/suggestion
Requirements:
  • Text must be selected
  • Editor must be focused
  • Browser must support clipboard API
Debug:
// Check selection in browser console:
const selection = editorView.state.selection.main;
console.log(selection.empty); // Should be false
Common issues:
  • Network connectivity
  • Convex database unavailable
  • File size too large (>1MB)
Check status:
# Look for save indicator in editor tab
# Check network tab for failed PUT requests
Requirements:
  • Modern browser (Chrome, Edge, or Firefox)
  • Sufficient RAM (2GB+ recommended)
  • Third-party cookies enabled
Troubleshoot:
# Check browser console for WebContainer errors
# Try reloading the page
# Clear browser cache
For more help, visit our Discord community or check the GitHub issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us