1# Smart Placement Patterns
2 
3## Backend Worker with Database Access
4 
5```typescript
6export default {
7  async fetch(request: Request, env: Env): Promise<Response> {
8    const user = await env.DATABASE.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();
9    const orders = await env.DATABASE.prepare('SELECT * FROM orders WHERE user_id = ?').bind(userId).all();
10    return Response.json({ user, orders });
11  }
12};
13```
14 
15```jsonc
16{ "placement": { "mode": "smart" }, "d1_databases": [{ "binding": "DATABASE", "database_id": "xxx" }] }
17```
18 
19## Frontend + Backend Split (Service Bindings)
20 
21**Frontend:** Runs at edge for fast user response
22**Backend:** Smart Placement runs close to database
23 
24```typescript
25// Frontend Worker - routes requests to backend
26interface Env {
27  BACKEND: Fetcher;  // Service Binding to backend Worker
28}
29 
30export default {
31  async fetch(request: Request, env: Env): Promise<Response> {
32    if (new URL(request.url).pathname.startsWith('/api/')) {
33      return env.BACKEND.fetch(request);  // Forward to backend
34    }
35    return new Response('Frontend content');
36  }
37};
38 
39// Backend Worker - database operations
40interface BackendEnv {
41  DATABASE: D1Database;
42}
43 
44export default {
45  async fetch(request: Request, env: BackendEnv): Promise<Response> {
46    const data = await env.DATABASE.prepare('SELECT * FROM table').all();
47    return Response.json(data);
48  }
49};
50```
51 
52**CRITICAL:** Use fetch-based Service Bindings (shown above). If using RPC with `WorkerEntrypoint`, Smart Placement will NOT optimize those method calls - only `fetch` handlers are affected.
53 
54**RPC vs Fetch - CRITICAL:** Smart Placement ONLY works with fetch-based bindings, NOT RPC.
55 
56```typescript
57// ❌ RPC - Smart Placement has NO EFFECT on backend RPC methods
58export class BackendRPC extends WorkerEntrypoint {
59  async getData() {
60    // ALWAYS runs at edge, Smart Placement ignored
61    return await this.env.DATABASE.prepare('SELECT * FROM table').all();
62  }
63}
64 
65// ✅ Fetch - Smart Placement WORKS
66export default {
67  async fetch(request: Request, env: Env): Promise<Response> {
68    // Runs close to DATABASE when Smart Placement enabled
69    const data = await env.DATABASE.prepare('SELECT * FROM table').all();
70    return Response.json(data);
71  }
72};
73```
74 
75## External API Integration
76 
77```typescript
78export default {
79  async fetch(request: Request, env: Env): Promise<Response> {
80    const apiUrl = 'https://api.partner.com';
81    const headers = { 'Authorization': `Bearer ${env.API_KEY}` };
82    
83    const [profile, transactions] = await Promise.all([
84      fetch(`${apiUrl}/profile`, { headers }),
85      fetch(`${apiUrl}/transactions`, { headers })
86    ]);
87    
88    return Response.json({ 
89      profile: await profile.json(), 
90      transactions: await transactions.json()
91    });
92  }
93};
94```
95 
96## SSR / API Gateway Pattern
97 
98```typescript
99// Frontend (edge) - auth/routing close to user
100export default {
101  async fetch(request: Request, env: Env) {
102    if (!request.headers.get('Authorization')) {
103      return new Response('Unauthorized', { status: 401 });
104    }
105    const data = await env.BACKEND.fetch(request);
106    return new Response(renderPage(await data.json()), { 
107      headers: { 'Content-Type': 'text/html' } 
108    });
109  }
110};
111 
112// Backend (Smart Placement) - DB operations close to data
113export default {
114  async fetch(request: Request, env: Env) {
115    const data = await env.DATABASE.prepare('SELECT * FROM pages WHERE id = ?').bind(pageId).first();
116    return Response.json(data);
117  }
118};
119```
120 
121## Durable Objects with Smart Placement
122 
123**Key principle:** Smart Placement does NOT control WHERE Durable Objects run. DOs always run in their designated region (based on jurisdiction or smart location hints).
124 
125**What Smart Placement DOES affect:** The location of the coordinator Worker's `fetch` handler that makes calls to multiple DOs.
126 
127**Pattern:** Enable Smart Placement on coordinator Worker that aggregates data from multiple DOs:
128 
129```typescript
130// Worker with Smart Placement - aggregates data from multiple DOs
131export default {
132  async fetch(request: Request, env: Env): Promise<Response> {
133    const userId = new URL(request.url).searchParams.get('user');
134    
135    // Get DO stubs
136    const userDO = env.USER_DO.get(env.USER_DO.idFromName(userId));
137    const analyticsID = env.ANALYTICS_DO.idFromName(`analytics-${userId}`);
138    const analyticsDO = env.ANALYTICS_DO.get(analyticsID);
139    
140    // Fetch from multiple DOs
141    const [userData, analyticsData] = await Promise.all([
142      userDO.fetch(new Request('https://do/profile')),
143      analyticsDO.fetch(new Request('https://do/stats'))
144    ]);
145    
146    return Response.json({
147      user: await userData.json(),
148      analytics: await analyticsData.json()
149    });
150  }
151};
152```
153 
154```jsonc
155// wrangler.jsonc
156{
157  "placement": { "mode": "smart" },
158  "durable_objects": {
159    "bindings": [
160      { "name": "USER_DO", "class_name": "UserDO" },
161      { "name": "ANALYTICS_DO", "class_name": "AnalyticsDO" }
162    ]
163  }
164}
165```
166 
167**When this helps:** 
168- Worker's `fetch` handler runs closer to DO regions, reducing network latency for multiple DO calls
169- Most beneficial when DOs are geographically concentrated or in specific jurisdictions
170- Helps when coordinator makes many sequential or parallel DO calls
171 
172**When this DOESN'T help:**
173- DOs are globally distributed (no single optimal Worker location)
174- Worker only calls a single DO
175- DO calls are infrequent or cached
176 
177## Best Practices
178 
179- Split full-stack apps: frontend at edge, backend with Smart Placement
180- Use fetch-based Service Bindings (not RPC)
181- Enable for backend logic: APIs, data aggregation, DB operations
182- Don't enable for: static content, edge logic, RPC methods, Pages with `run_worker_first`
183- Wait 15+ min for analysis, verify `placement_status = SUCCESS`
184