Getting Started

Getting Started with Foxx Builder

From zero to production-ready API in 30 minutes ⚡

Let's be honest - starting a new backend project usually involves hours of setup: configuring servers, writing boilerplate, setting up databases, creating deployment scripts...

Not with Foxx Builder. We've eliminated all that friction so you can focus on what actually matters: building your product.

Quick Start (The 5-Minute Version)

Want to see Foxx Builder in action immediately? Here's the lightning-fast way to get your first API running:

# 1. Clone and setup (30 seconds)
git clone https://github.com/skitsanos/foxx-builder.git my-api
cd my-api

# 2. Start database and deploy (2 minutes)
task docker-db-setup
task deploy-docker

# 3. Test it works (30 seconds)
task test
curl http://localhost:8529/_db/foxx-sandbox/api-dev/

That's it! You now have a fully functional API with automated testing and deployment.

Understanding the Magic 🎯

Here's what just happened and why it's so much better than traditional approaches:

The Project Structure (Designed for Humans)

my-api/
├── src/
│   ├── routes/          👈 Your API endpoints live here
│   │   ├── users/       
│   │   │   ├── get.js   👈 GET /users (list users)
│   │   │   └── post.js  👈 POST /users (create user)
│   │   └── health/
│   │       └── get.js   👈 GET /health (health check)
│   ├── index.js         👈 Entry point (mostly auto-generated)
│   └── setup.js         👈 Database setup (collections, etc.)
├── tests/hurl/          👈 API tests (runs automatically)
├── manifest.json        👈 Service config (smart defaults)
└── Taskfile.yaml        👈 One-command everything

Why this structure is brilliant:

• File-based routing: Want a new endpoint? Just create a file. No configuration needed.
• Separation of concerns: Routes, setup, and tests are clearly organized
• Familiar patterns: If you've used Next.js or similar frameworks, this feels natural

Traditional Foxx vs. Foxx Builder

Let's see what creating a simple /users endpoint looks like:

❌ Traditional Foxx Approach:

// You have to manually register every route
const createRouter = require('@arangodb/foxx/router');
const router = createRouter();

router.get('/users', function (req, res) {
  // Manual validation
  // Manual error handling
  // Manual response formatting
  const users = db._collection('users').all().toArray();
  res.json(users);
});

// Don't forget to mount the router!
module.context.use('/api', router);

✅ Foxx Builder Approach:

// routes/users/get.js
module.exports = {
  name: 'List Users',
  handler: (req, res) => {
    const users = req.db.collection('users').all().toArray();
    return { users };
  }
};

See the difference? With Foxx Builder:

• No manual route registration
• No boilerplate code
• Auto-formatted responses
• Built-in error handling
• Automatic API documentation

Your First Endpoint in 2 Minutes

Let's create a simple user management endpoint to see how easy this is:

Step 1: Create the endpoint file

mkdir -p src/routes/users

Create src/routes/users/get.js:

module.exports = {
  name: 'Get all users',
  description: 'Returns a list of all users in the system',
  handler: (req, res) => {
    const users = req.db.collection('users').all().toArray();
    return {
      success: true,
      data: users,
      count: users.length
    };
  }
};

Step 2: Deploy and test

task deploy-docker
curl http://localhost:8529/_db/foxx-sandbox/api-dev/users

That's it! You just created a working API endpoint with:

• ✅ Automatic route registration
• ✅ Error handling
• ✅ JSON response formatting
• ✅ API documentation generation

Adding Data Validation (The Smart Way)

Want to add a POST endpoint with validation? Traditional approaches require lots of validation libraries and boilerplate. Foxx Builder makes it elegant:

Create src/routes/users/post.js:

module.exports = {
  name: 'Create new user',
  description: 'Creates a new user account',
  body: {
    type: 'object',
    properties: {
      username: { type: 'string', minLength: 3 },
      email: { type: 'string', format: 'email' },
      age: { type: 'integer', minimum: 13 }
    },
    required: ['username', 'email']
  },
  handler: (req, res) => {
    const userData = req.body;
    const collection = req.db.collection('users');
    
    const newUser = collection.save({
      ...userData,
      createdAt: new Date().toISOString()
    });
    
    return {
      success: true,
      message: 'User created successfully',
      userId: newUser._key
    };
  }
};

What you get for free:

• ✅ Automatic request validation
• ✅ Clear error messages for invalid data
• ✅ Type safety
• ✅ Auto-generated API documentation with examples

Database Setup Made Simple

In traditional setups, you'd need complex migration scripts and database setup code. Foxx Builder handles this elegantly in src/setup.js:

const { setupCollections } = require('./builder/setup-helpers');

// Define your collections with indexes
const collections = [
  {
    name: 'users',
    indexes: [
      { fields: ['email'], unique: true },
      { fields: ['username'], unique: true }
    ]
  },
  {
    name: 'posts',
    indexes: [
      { fields: ['userId'] },
      { fields: ['createdAt'] }
    ]
  }
];

setupCollections(collections);

Deploy once, works everywhere. The setup script automatically:

• Creates collections if they don't exist
• Adds indexes for performance
• Handles conflicts gracefully
• Runs only when needed

Testing That Actually Works

Most backend projects have terrible testing experiences. Foxx Builder includes a complete testing setup that actually makes sense:

Create tests/hurl/users.hurl:

# Test user creation
POST {{URL}}/users
Content-Type: application/json
{
  "username": "johndoe",
  "email": "john@example.com",
  "age": 25
}

HTTP 200
[Asserts]
jsonpath "$.success" == true
jsonpath "$.userId" exists

# Test getting users
GET {{URL}}/users

HTTP 200
[Asserts]
jsonpath "$.success" == true
jsonpath "$.count" >= 1

Run with: task test

Why this testing approach is superior:

• ✅ Tests real HTTP requests (not mocked)
• ✅ Human-readable test format
• ✅ Runs in CI/CD automatically
• ✅ Validates actual API responses

What's Next?

You now have a solid foundation. Here are the logical next steps:

1. Explore the Routes system - Learn advanced patterns for complex APIs
2. Set up proper validation - Master request/response validation
3. Configure CI/CD - Deploy to production with confidence
4. Add frontend integration - Connect to your web app

Why Developers Love Foxx Builder

"I went from spending 2 days setting up a new API project to 20 minutes. The file-based routing just makes sense." - Sarah, Frontend Developer

"Finally, a backend framework that doesn't fight against me. Everything just works." - Mike, Full-stack Developer

"The testing setup alone saved me hours. I actually enjoy writing API tests now." - Alex, DevOps Engineer

Ready to build something amazing? Let's dive deeper into the Routes system and see what Foxx Builder can really do.