Quick Start Guide

Get up and running with Andromeda in just a few minutes! This guide will walk you through creating your first Andromeda programs.

Your First Program

Create a simple "Hello, World!" program:

// hello.ts
console.log("Hello, Andromeda! 🌌");
console.log("Current time:", new Date().toISOString());

Run it:

andromeda run hello.ts

Output:

Hello, Andromeda! 🌌
Current time: 2025-06-08T15:30:45.123Z

Working with Files

Andromeda provides simple file I/O operations:

// file-example.ts

// Write some data to a file
const data = `# My Notes
- Learn Andromeda
- Build something cool
- Share with friends
`;

Andromeda.writeTextFileSync("notes.md", data);
console.log("✅ File written successfully!");

// Read the file back
const content = Andromeda.readTextFileSync("notes.md");
console.log("📄 File contents:");
console.log(content);

// Check environment variables
const home = Andromeda.env.get("HOME") || Andromeda.env.get("USERPROFILE");
console.log("🏠 Home directory:", home);

Run it:

andromeda run file-example.ts

Creating Graphics with Canvas

Andromeda includes a powerful Canvas API for creating graphics:

// graphics.ts

// Create a canvas
const canvas = new OffscreenCanvas(400, 300);
const ctx = canvas.getContext("2d")!;

// Set background
ctx.fillStyle = "#1a1a1a";
ctx.fillRect(0, 0, 400, 300);

// Draw colorful rectangles
const colors = ["#ff6b6b", "#4ecdc4", "#45b7d1", "#96ceb4", "#feca57"];

for (let i = 0; i < colors.length; i++) {
  ctx.fillStyle = colors[i];
  ctx.fillRect(50 + i * 60, 100, 50, 100);
}

// Add some text
ctx.fillStyle = "#ffffff";
ctx.font = "24px Arial";
ctx.fillText("Hello, Andromeda!", 100, 50);

// Save the image
canvas.render();
canvas.saveAsPng("my-first-graphic.png");

console.log("🎨 Image saved as 'my-first-graphic.png'");

Run it:

andromeda run graphics.ts

Using Cryptography

Generate secure random values and perform hashing:

// crypto-example.ts

// Generate a random UUID
const id = crypto.randomUUID();
console.log("🆔 Random UUID:", id);

// Generate random bytes
const randomBytes = crypto.getRandomValues(new Uint8Array(16));
console.log(
  "🎲 Random bytes:",
  Array.from(randomBytes).map((b) => b.toString(16).padStart(2, "0")).join(""),
);

// Hash some data
const data = new TextEncoder().encode("Hello, Andromeda!");
const hashBuffer = await crypto.subtle.digest("SHA-256", data);
const hashArray = new Uint8Array(hashBuffer);
const hashHex = Array.from(hashArray).map((b) =>
  b.toString(16).padStart(2, "0")
).join("");

console.log("🔒 SHA-256 hash:", hashHex);

Run it:

andromeda run crypto-example.ts

Performance Monitoring

Monitor execution performance:

// performance-example.ts

// Measure execution time
const start = performance.now();

// Simulate some work
let sum = 0;
for (let i = 0; i < 1000000; i++) {
  sum += Math.sqrt(i);
}

const end = performance.now();
const duration = end - start;

console.log(`⚡ Calculated sum: ${sum.toFixed(2)}`);
console.log(`⏱️  Execution time: ${duration.toFixed(2)}ms`);

// Use performance marks
performance.mark("data-processing-start");

// More work
const data = Array.from({ length: 10000 }, (_, i) => Math.random() * i);
const sorted = data.sort((a, b) => a - b);

performance.mark("data-processing-end");
performance.measure(
  "data-processing",
  "data-processing-start",
  "data-processing-end",
);

console.log(`📊 Processed ${sorted.length} items`);

Run it:

andromeda run performance-example.ts

Using SQLite Database

Andromeda includes built-in SQLite support for data persistence:

// sqlite-example.ts

// Create or open a database
const db = new DatabaseSync("notes.db");

// Create table
db.exec(`
  CREATE TABLE IF NOT EXISTS notes (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    content TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
  )
`);

// Insert data
const insertNote = db.prepare(
  "INSERT INTO notes (title, content) VALUES (?, ?)",
);
const result = insertNote.run("My First Note", "This is stored in SQLite!");

console.log(`📝 Created note with ID: ${result.lastInsertRowid}`);

// Query data
const selectNotes = db.prepare("SELECT * FROM notes ORDER BY created_at DESC");
const notes = selectNotes.all();

console.log("📚 All notes:");
for (const note of notes) {
  console.log(`- ${note.title} (${note.created_at})`);
}

// Clean up
insertNote.finalize();
selectNotes.finalize();
db.close();

Using the Interactive REPL

Start the REPL for interactive development:

andromeda repl

Try these commands in the REPL:

// Basic calculations
> 2 + 2
4

// Create a canvas
> const canvas = new OffscreenCanvas(100, 100)
> const ctx = canvas.getContext("2d")
> ctx.fillStyle = "red"
> ctx.fillRect(0, 0, 50, 50)

// File operations
> Andromeda.writeTextFileSync("test.txt", "Hello from REPL!")
> Andromeda.readTextFileSync("test.txt")
"Hello from REPL!"

// SQLite database
> const db = new DatabaseSync(":memory:")
> db.exec("CREATE TABLE test (id INTEGER, name TEXT)")
> const stmt = db.prepare("INSERT INTO test VALUES (?, ?)")
> stmt.run(1, "Test Item")
> db.prepare("SELECT * FROM test").all()
[{ id: 1, name: "Test Item" }]

// Crypto
> crypto.randomUUID()
"12345678-1234-1234-1234-123456789abc"

Type help for available REPL commands, or exit to quit.

Running Multiple Files

You can run multiple files together:

andromeda run utils.ts main.ts helper.ts

Code Formatting

Format your TypeScript/JavaScript files:

# Format specific files
andromeda fmt hello.ts graphics.ts

# Format entire directory
andromeda fmt src/

# Format current directory
andromeda fmt

Upgrading Andromeda

Keep your runtime up to date:

# Check for and install updates
andromeda upgrade

# See what would be updated without installing
andromeda upgrade --dry-run

Next Steps

Now that you've got the basics down:

Explore the APIs: Check out the API Documentation for detailed information about available functions
Join the Community: Connect with other developers on Discord

Common Patterns

Error Handling

try {
  const content = Andromeda.readTextFileSync("nonexistent.txt");
  console.log(content);
} catch (error) {
  console.error("❌ Failed to read file:", error.message);
}

Async Operations

// Using crypto with async/await
async function hashData(input: string) {
  const data = new TextEncoder().encode(input);
  const hash = await crypto.subtle.digest("SHA-256", data);
  return new Uint8Array(hash);
}

const result = await hashData("Hello, World!");
console.log("Hash result:", result);

Environment Configuration

// Check if we're in development mode
const isDev = Andromeda.env.get("NODE_ENV") !== "production";

if (isDev) {
  console.log("🚧 Running in development mode");
}

// Get command line arguments
console.log("📋 Arguments:", Andromeda.args);

Happy coding with Andromeda! 🚀