| name | deploying-to-globe |
| description | Deploys Dart and Flutter applications to Globe.dev serverless platform. Use when deploying apps, configuring globe.yaml, Globe KV, Globe DB, Globe AI, cron jobs, custom domains, environment variables, or troubleshooting Globe errors. |
Globe Deployment Skill
Globe is a serverless deployment platform for Dart and Flutter applications. Apps compile to x86_64 native executables and deploy to 300+ edge locations with automatic scaling.
Critical Requirements
All Globe server apps MUST:
- Listen on
PORT environment variable (not hardcoded):
final port = int.parse(Platform.environment['PORT'] ?? '8080');
-
Be stateless — no local file persistence between requests
-
Compile FFI to x86_64 if using native code
CLI Quick Reference
dart pub global activate globe_cli
globe login
globe logout
globe link
globe unlink
globe create -t <tpl>
globe deploy
globe deploy --prod
globe build-logs
globe token create
globe token list
globe token delete
Global flags: --help, --verbose, --token <t>, --project <id>, --org <id>
globe.yaml (Optional)
Globe auto-detects most project types. A globe.yaml is required for:
- Cron jobs — must be defined in config file
- Static assets — must be defined in config file
Other settings (preferred regions, build settings, etc.) can be configured via the dashboard instead.
Example (when needed):
entrypoint: bin/server.dart
build:
preset:
type: dart_frog
assets:
- public/
crons:
- id: daily_cleanup
schedule: "0 0 * * *"
path: "/cron/cleanup"
Validate (if globe.yaml exists):
bash scripts/validate-globe-yaml.sh globe.yaml
Build Presets
| Preset | Use Case |
|---|
dart_frog | File-based routing APIs |
shelf | Flexible Dart servers (manual config) |
flutter | Flutter Web SPAs |
flutter_server | Flutter with server-side rendering |
jaspr | Jaspr SSR sites |
jaspr_static | Jaspr static site generation |
serverpod | Full-stack Dart framework |
Common Code Patterns
Shelf Hello World
import 'dart:io';
import 'package:shelf/shelf.dart';
import 'package:shelf/shelf_io.dart' as io;
void main() async {
final port = int.parse(Platform.environment['PORT'] ?? '8080');
final handler = const Pipeline()
.addMiddleware(logRequests())
.addHandler((req) => Response.ok('Hello from Globe!'));
await io.serve(handler, InternetAddress.anyIPv4, port);
}
Environment Variables
// User-defined secrets (set in Globe dashboard)
final apiKey = Platform.environment['API_KEY'];
final dbUrl = Platform.environment['DATABASE_URL'];
// Globe system variables (auto-set)
final isGlobe = Platform.environment['GLOBE'] == '1';
final buildEnv = Platform.environment['GLOBE_BUILD_ENV']; // 'preview' or 'production'
Cron Job Handler
// Cron jobs POST to your path at scheduled times
app.post('/cron/daily', (Request req) async {
final cronId = req.headers['x-globe-cron-id'];
// Do work...
return Response.ok('done'); // 2xx = success
});
Globe KV (Key-Value Store)
import 'package:globe_kv/globe_kv.dart';
final kv = GlobeKV('namespace-id'); // Create namespace in dashboard first
await kv.set('key', 'value', ttl: 3600); // TTL in seconds
final value = await kv.getString('key');
await kv.delete('key');
final keys = await kv.list(prefix: 'user:', limit: 100);
Globe DB (SQLite)
import 'package:drift/drift.dart';
import 'package:drift/native.dart';
import 'package:sqlite3/sqlite3.dart';
// Connect to Globe DB (name from dashboard)
final db = NativeDatabase.opened(sqlite3.open('your-db-name.db'));
Globe AI
import 'package:globe_ai/globe_ai.dart';
final result = await generateText(
model: openai.chat('gpt-4o'),
prompt: 'What is the capital of France?',
);
globe.yaml Full Example
entrypoint: bin/server.dart
build:
preset:
type: dart_frog
version: "2.0.0"
buildCommand: "custom"
build_runner:
automatic_detection: true
command: "dart run build_runner build"
melos:
automatic_detection: true
command: "melos bootstrap"
version: "3.0.0"
assets:
- public/
- assets/images/
crons:
- id: daily_cleanup
schedule: "0 0 * * *"
path: "/cron/cleanup"
preferred_regions:
- us-east1
- europe-west1
Preferred Regions
Valid values for preferred_regions:
africa-south1, asia-east1, asia-east2, asia-northeast1, asia-northeast2,
asia-northeast3, asia-south1, asia-south2, asia-southeast1, asia-southeast2,
australia-southeast1, australia-southeast2, europe-central2, europe-north1,
europe-southwest1, europe-west1, europe-west2, europe-west3, europe-west4,
europe-west6, europe-west8, europe-west9, europe-west10, europe-west12,
me-central1, me-central2, me-west1, northamerica-northeast1, northamerica-northeast2,
northamerica-south1, southamerica-east1, southamerica-west1, us-central1,
us-east1, us-east4, us-east5, us-south1, us-west1, us-west2, us-west4
System Environment Variables
| Variable | Description |
|---|
PORT | Port your server must listen on |
GLOBE | "1" when running on Globe |
GLOBE_BUILD_ENV | "1" during build phase |
HOSTNAME | Container hostname |
CRON_ID | Cron job ID (if cron-triggered) |
CRON_SCHEDULE | Cron schedule expression |
Globe Request Headers
Globe adds these headers to incoming requests:
x-globe-country — ISO country codex-globe-city — City namex-globe-region — Region/statex-globe-latitude / x-globe-longitude — Coordinatesx-globe-timezone — IANA timezonex-globe-temperature — cold, warm, or hot (container state)
Resource Limits
| Resource | Limit |
|---|
| Requests | 50K/month |
| Compute Bandwidth | 1GB/month |
| Asset Bandwidth | 1GB/month |
| Memory | 256MB/container |
| Execution Time | 30 seconds/request |
| Databases | 2 active |
| Cron Jobs | 1 job (unlimited invocations) |
Error Quick Fixes
| Error | Cause | Fix |
|---|
| 413 | Archive >100MB | Add large files to .gitignore |
| 503 on deploy | Build failed | Check globe build-logs |
| Cold start slow | First request initializes | Use preferred_regions in globe.yaml |
| CORS errors | Missing headers | Add CORS middleware |
| Domain not working | DNS not propagated | Wait 24h, verify CNAME to domains.globeapp.dev |
Reference Documentation
Load the appropriate reference file based on user intent. For topics not listed, explore the references/ folder.
Getting Started
Core Concepts
CLI Commands
Frameworks
Products
Infrastructure
Guides
Tutorials
Troubleshooting
Deployment Workflow
Copy this checklist and track progress:
Deployment Progress:
- [ ] Step 1: Verify PORT usage in code
- [ ] Step 2: Create globe.yaml (only if needed for crons/assets/regions)
- [ ] Step 3: Set environment variables in dashboard (if needed)
- [ ] Step 4: Run `globe deploy` for preview
- [ ] Step 5: Test preview URL
- [ ] Step 6: Run `globe deploy --prod` for production
- [ ] Step 7: Configure custom domain (if needed)
Step 1: Ensure server listens on Platform.environment['PORT']
Step 2: Create globe.yaml only if you need cron jobs or static assets. Globe auto-detects presets for most projects.
Step 3: Add secrets via Dashboard → Settings → Environment Variables
Step 4: Deploy preview: globe deploy
Step 5: Test the preview URL thoroughly
Step 6: Deploy production: globe deploy --prod
Step 7: Add custom domain via Dashboard → Domains → CNAME to domains.globeapp.dev
Decision Tree
Deploying Dart/Flutter to Globe?
├── New project?
│ ├── Yes → globe create -t <template>
│ └── No → globe link
│
├── Framework?
│ ├── Dart Frog → preset: dart_frog (auto-detected)
│ ├── Shelf → preset: shelf
│ ├── Flutter Web → preset: flutter
│ └── Jaspr → preset: jaspr
│
├── Deployment type?
│ ├── Preview → globe deploy
│ └── Production → globe deploy --prod
│
├── Needs caching?
│ └── Globe KV → Create namespace in dashboard, use globe_kv package
│
├── Needs database?
│ └── Globe DB → Create in dashboard, use Drift with sqlite3
│
├── Needs AI?
│ └── Globe AI → Install globe_ai, configure model provider
│
├── Background jobs?
│ └── Add crons to globe.yaml, handler returns 2xx
│
├── Custom domain?
│ └── Dashboard → Domains → Add → CNAME to domains.globeapp.dev
│
└── CI/CD?
├── GitHub → Enable GitHub integration
└── Other → globe token create
