Getting Started

This guide will walk you through creating your first Arcade application, from installation to deployment.

Prerequisites

Before you begin, make sure you have:

• Dart SDK (3.0 or higher)
• A code editor (VS Code with Dart extension recommended)
• Basic knowledge of Dart programming

Installation

Create a new Dart project

dart create -t console my_arcade_app
cd my_arcade_app

Add Arcade dependency

Add Arcade to your pubspec.yaml:

dependencies:
  arcade: ^<latest-version>

Then install the dependencies:

dart pub get

Your First Server

Create a simple server in bin/server.dart:

import 'package:arcade/arcade.dart';

Future<void> main() async {
  await runServer(
    port: 3000,
    init: () {
      // Define your routes here
      route.get('/').handle((context) => 'Hello, Arcade!');

      route.get('/api/health').handle((context) {
        return {'status': 'ok', 'timestamp': DateTime.now().toIso8601String()};
      });
    },
  );
}

Run the server

dart run bin/server.dart

You should see:

Server running on port 3000

Visit http://localhost:3000 to see your server in action!

Understanding the Basics

The runServer function

The runServer function is the entry point for your Arcade application:

await runServer(
  port: 3000,              // Port to listen on
  init: () {               // Initialization function
    // Define routes, configure services, etc.
  },
  logLevel: LogLevel.info, // Optional: Set log level
);

Routes

Routes in Arcade follow a simple pattern:

route.<method>(path).<hooks>?.handle(handler);

For example:

// Simple GET route
route.get('/users').handle((context) => 'List of users');

// POST route with before hook
route.post('/users')
  .before((context) {
    // Validate request
    return context;
  })
  .handle((context) async {
    final body = await context.jsonMap();
    // Create user
    return {'created': true};
  });

Request Context

Every handler receives a RequestContext object that provides access to:

• Request data (headers, body, parameters)
• Response utilities
• Route information

route.get('/users/:id').handle((context) {
  final userId = context.pathParameters['id'];
  final filter = context.queryParameters['filter'];

  return {
    'userId': userId,
    'filter': filter,
    'requestedAt': DateTime.now().toIso8601String(),
  };
});

Adding More Features

Handling JSON bodies

route.post('/api/users').handle((context) async {
  final result = await context.jsonMap();

  if (result case BodyParseSuccess(:final value)) {
    // Process the JSON data
    final name = value['name'];
    final email = value['email'];

    return {'id': 123, 'name': name, 'email': email};
  } else {
    context.statusCode = 400;
    return {'error': 'Invalid JSON body'};
  }
});

Error handling

route.get('/api/protected').handle((context) {
  final token = context.requestHeaders.value('authorization');

  if (token == null) {
    throw UnauthorizedException();
  }

  return {'secret': 'data'};
});

// Global error handler
overrideErrorHandler((context, error, stackTrace) {
  if (error is UnauthorizedException) {
    context.statusCode = 401;
    return {'error': 'Unauthorized'};
  }

  context.statusCode = 500;
  return {'error': 'Internal server error'};
});

Static files

To serve static files, create a public directory in your project root:

my_arcade_app/
├── bin/
│   └── server.dart
├── public/
│   ├── index.html
│   └── style.css
└── pubspec.yaml

Arcade will automatically serve files from the public directory.

Project Structure

Here’s a recommended project structure for Arcade applications:

my_arcade_app/
├── bin/
│   └── server.dart          # Entry point
├── lib/
│   ├── controllers/         # Route handlers
│   ├── services/           # Business logic
│   ├── models/             # Data models
│   └── hooks/              # Reusable hooks
├── public/                 # Static files
├── test/                   # Tests
└── pubspec.yaml

Environment Configuration

Use environment variables for configuration:

import 'dart:io';

Future<void> main() async {
  final port = int.parse(Platform.environment['PORT'] ?? '3000');
  final dbUrl = Platform.environment['DATABASE_URL'] ?? 'localhost';

  await runServer(
    port: port,
    init: () {
      // Use dbUrl to connect to database
      route.get('/').handle((context) => 'Server running on port $port');
    },
  );
}

Next Steps

Now that you have a basic Arcade server running, explore these topics:

• Core Concepts - Deep dive into routing
• Request Handling - Working with requests and responses
• Hooks - Adding before/after hooks
• WebSockets - Real-time communication
• Dependency Injection - Structuring larger applications

Getting Help

If you run into issues:

1. Check the API Reference
2. Look at the example applications
3. Open an issue on GitHub

Happy coding with Arcade!