@terreno/admin-backend 58.0.0-beta.1 → 58.0.0-beta.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,357 +0,0 @@
1
- ---
2
- description: Terreno monorepo root guidelines
3
- globs: **/*
4
- ---
5
-
6
- # Terreno
7
-
8
- Terreno is Django/Rails for TypeScript — with universal app support.
9
-
10
- Terreno is Django/Rails for TypeScript — a batteries-included, full-stack
11
- framework where the undifferentiated 80% of an app is already written. On the
12
- backend you get Mongoose models, auto-generated REST APIs, permissions, an admin
13
- panel, authentication, and an AI service. On the frontend you get one universal
14
- app — a single React Native codebase that ships to iOS, Android, and web. It is
15
- built to be driven by AI coding agents from the first prompt to a production
16
- deploy.
17
-
18
- - Batteries included — auth, CRUD APIs, admin, permissions, AI, realtime,
19
- feature flags, and consent are already built, so your code is business logic.
20
- - Universal by default — one React Native codebase ships to iOS, Android, and
21
- web. Not a web framework with a mobile bolt-on.
22
- - AI-native — agents are a first-class client of the framework, not an
23
- afterthought.
24
-
25
- ## Packages
26
-
27
- - **api/** - REST API framework built on Express/Mongoose (`@terreno/api`)
28
- - **ui/** - React Native UI component library (`@terreno/ui`)
29
- - **rtk/** - Redux Toolkit Query utilities for API backends (`@terreno/rtk`)
30
- - **admin-backend/** - Admin panel backend plugin for @terreno/api (`@terreno/admin-backend`)
31
- - **admin-frontend/** - Admin panel frontend screens for @terreno/api backends (`@terreno/admin-frontend`)
32
- - **mcp-server/** - MCP server for AI assistant integration (`@terreno/mcp-server`)
33
- - **demo/** - Demo app for showcasing and testing UI components
34
- - **example-frontend/** - Example Expo app demonstrating full stack usage
35
- - **example-backend/** - Example Express backend using @terreno/api
36
-
37
- ## Development
38
-
39
- Uses [Bun](https://bun.sh/) as the package manager.
40
-
41
- ```bash
42
- bun install # Install dependencies
43
- bun run compile # Compile all packages
44
- bun run lint # Lint all packages
45
- bun run lint:fix # Fix lint issues
46
- bun run test # Run tests in api and ui
47
- ```
48
-
49
- ### Package-specific commands
50
-
51
- ```bash
52
- bun run api:test # Test API package
53
- bun run ui:test # Test UI package
54
- bun run demo:start # Start demo app
55
- bun run frontend:web # Start frontend example
56
- bun run backend:dev # Start backend example
57
- bun run mcp:build # Build MCP server
58
- bun run mcp:start # Start MCP server
59
- bun run admin-backend:compile # Compile admin backend
60
- bun run admin-frontend:compile # Compile admin frontend
61
- ```
62
-
63
- ## How the Packages Work Together
64
-
65
- The three core packages form a complete full-stack framework:
66
-
67
- ```
68
- BACKEND
69
- @terreno/api
70
- - Mongoose models with modelRouter -> CRUD endpoints
71
- - Built-in auth (JWT + Passport)
72
- - Automatic OpenAPI spec generation
73
- |
74
- /openapi.json
75
- |
76
- RTK Query SDK Codegen
77
- |
78
- FRONTEND
79
- @terreno/rtk
80
- - Generated hooks from OpenAPI spec
81
- - Auth slice with JWT token management
82
- - Automatic token refresh
83
- +
84
- @terreno/ui
85
- - React Native components (Box, Button, TextField, etc.)
86
- - TerrenoProvider for theming
87
- ```
88
-
89
- ### Integration Flow
90
-
91
- 1. **Backend (api)**: Define Mongoose models, use `modelRouter` to create CRUD endpoints with permissions
92
- 2. **OpenAPI Generation**: `setupServer` automatically generates `/openapi.json`
93
- 3. **SDK Codegen**: Frontend runs `bun run sdk` to generate RTK Query hooks from OpenAPI spec
94
- 4. **Frontend (rtk + ui)**: Use generated hooks with UI components for type-safe API calls
95
-
96
- ## Example Apps (Keep These Updated!)
97
-
98
- The `example-frontend/` and `example-backend/` directories serve as both documentation and integration tests. When adding features to api, ui, or rtk:
99
-
100
- 1. **Add examples** demonstrating new features
101
- 2. **Update SDK** after backend changes: `cd example-frontend && bun run sdk`
102
- 3. **Verify integration** by running both examples together
103
-
104
- ### Running the Full Stack
105
-
106
- ```bash
107
- # Terminal 1: Start backend
108
- bun run backend:dev
109
-
110
- # Terminal 2: Start frontend
111
- bun run frontend:web
112
- ```
113
-
114
- ## Code Style
115
-
116
- ### TypeScript/JavaScript
117
- - Use ES module syntax and TypeScript for all code
118
- - Prefer interfaces over types; avoid enums, use maps
119
- - Prefer const arrow functions over `function` keyword
120
- - Use descriptive variable names with auxiliary verbs (e.g., `isLoading`)
121
- - Use camelCase directories (e.g., `components/authWizard`)
122
- - Favor named exports
123
- - Use the RORO pattern (Receive an Object, Return an Object)
124
-
125
- ### Dates and Time
126
- - Always use Luxon instead of Date or dayjs
127
-
128
- ### Error Handling
129
- - Check error conditions at start of functions and return early
130
- - Limit nested if statements
131
- - Use multiline syntax with curly braces for all conditionals
132
-
133
- ### Testing
134
- - Use bun test with expect for testing
135
-
136
- ### Logging
137
- - Frontend: Use `console.info`, `console.debug`, `console.warn`, or `console.error` for permanent logs
138
- - Backend: Use `logger.info/warn/error/debug` for permanent logs
139
- - Use `console.log` only for debugging (to be removed)
140
-
141
- ### Development Practices
142
- - Don't apologize for errors: fix them
143
- - Prioritize modularity, DRY, performance, and security
144
- - Focus on readability over performance
145
- - Write complete, functional code without TODOs when possible
146
- - Comments should describe purpose, not effect
147
-
148
- ## Package Reference
149
-
150
- ### @terreno/api
151
-
152
- REST API framework providing:
153
-
154
- - **modelRouter**: Auto-generates CRUD endpoints for Mongoose models
155
- - **Permissions**: `IsAuthenticated`, `IsOwner`, `IsAdmin`, `IsAuthenticatedOrReadOnly`
156
- - **Query Filters**: `OwnerQueryFilter` for filtering list queries by owner
157
- - **setupServer**: Express server setup with auth, OpenAPI, and middleware
158
- - **APIError**: Standardized error handling
159
- - **logger**: Winston-based logging
160
-
161
- Key imports:
162
- ```typescript
163
- import {
164
- modelRouter,
165
- setupServer,
166
- Permissions,
167
- OwnerQueryFilter,
168
- APIError,
169
- logger,
170
- asyncHandler,
171
- authenticateMiddleware,
172
- } from "@terreno/api";
173
- ```
174
-
175
- #### modelRouter Usage
176
-
177
- ```typescript
178
- import {modelRouter, modelRouterOptions, Permissions} from "@terreno/api";
179
-
180
- const router = modelRouter(YourModel, {
181
- permissions: {
182
- list: [Permissions.IsAuthenticated],
183
- create: [Permissions.IsAuthenticated],
184
- read: [Permissions.IsOwner],
185
- update: [Permissions.IsOwner],
186
- delete: [], // Disabled
187
- },
188
- sort: "-created",
189
- queryFields: ["_id", "type", "name"],
190
- });
191
- ```
192
-
193
- #### Custom Routes
194
-
195
- For non-CRUD endpoints, use the OpenAPI builder:
196
-
197
- ```typescript
198
- import {asyncHandler, authenticateMiddleware, createOpenApiBuilder} from "@terreno/api";
199
-
200
- router.get("/yourRoute/:id", [
201
- authenticateMiddleware(),
202
- createOpenApiBuilder(options)
203
- .withTags(["yourTag"])
204
- .withSummary("Brief summary")
205
- .withPathParameter("id", {type: "string"})
206
- .withResponse(200, {data: {type: "object"}})
207
- .build(),
208
- ], asyncHandler(async (req, res) => {
209
- return res.json({data: result});
210
- }));
211
- ```
212
-
213
- #### API Conventions
214
-
215
- - Throw `APIError` with appropriate status codes: `throw new APIError({status: 400, title: "Message"})`
216
- - Do not use `Model.findOne` - use `Model.findExactlyOne` or `Model.findOneOrThrow`
217
- - Define statics/methods by direct assignment: `schema.methods = {bar() {}}`
218
- - All model types live in `src/modelInterfaces.ts`
219
- - In routes: `req.user` is `UserDocument | undefined`
220
- - In @terreno/api callbacks: cast with `const user = u as unknown as UserDocument`
221
-
222
- ### @terreno/ui
223
-
224
- React Native UI component library (a large component library):
225
-
226
- - **Layout**: Box, Page, ListDetailLayout, SplitPage, Card
227
- - **Forms**: TextField, SelectField, DateTimeField, CheckBox
228
- - **Display**: Text, Heading, Badge, DataTable
229
- - **Actions**: Button, IconButton, Link
230
- - **Feedback**: Spinner, Modal, Toast
231
- - **Theming**: TerrenoProvider, useTheme
232
-
233
- Key imports:
234
- ```typescript
235
- import {
236
- Box,
237
- Button,
238
- Card,
239
- Page,
240
- Text,
241
- TextField,
242
- TerrenoProvider,
243
- } from "@terreno/ui";
244
- ```
245
-
246
- #### UI Component Examples
247
-
248
- Layout with Box:
249
- ```typescript
250
- <Box direction="row" padding={4} gap={2} alignItems="center">
251
- <Text>Content</Text>
252
- <Button text="Action" />
253
- </Box>
254
- ```
255
-
256
- Buttons:
257
- ```typescript
258
- <Button
259
- text="Submit"
260
- variant="primary" // 'primary' | 'secondary' | 'outline' | 'ghost'
261
- onClick={handleSubmit}
262
- loading={isLoading}
263
- iconName="check"
264
- />
265
- ```
266
-
267
- Forms:
268
- ```typescript
269
- <TextField
270
- label="Email"
271
- value={email}
272
- onChangeText={setEmail}
273
- error={emailError}
274
- helperText="Enter a valid email"
275
- />
276
- ```
277
-
278
- Modals:
279
- ```typescript
280
- <Modal
281
- title="Confirm Action"
282
- visible={isVisible}
283
- primaryButtonText="Confirm"
284
- secondaryButtonText="Cancel"
285
- onDismiss={() => setIsVisible(false)}
286
- onPrimaryAction={handleConfirm}
287
- >
288
- <Text>Are you sure?</Text>
289
- </Modal>
290
- ```
291
-
292
- #### UI Common Pitfalls
293
-
294
- - Don't use inline styles when theme values are available
295
- - Don't use raw `View`/`Text` when `Box`/@terreno/ui `Text` are available
296
- - Don't forget loading and error states
297
- - Don't use `style` prop when equivalent props exist (`padding`, `margin`)
298
- - Never modify `openApiSdk.ts` manually
299
-
300
- ### @terreno/rtk
301
-
302
- Redux Toolkit Query integration:
303
-
304
- - **generateAuthSlice**: Creates auth reducer and middleware with JWT handling
305
- - **emptyApi**: Base RTK Query API for code generation
306
- - **Platform utilities**: Secure token storage (expo-secure-store for native, AsyncStorage for web)
307
-
308
- Key imports:
309
- ```typescript
310
- import {generateAuthSlice} from "@terreno/rtk";
311
- ```
312
-
313
- Always use generated SDK hooks - never use `axios` or `request` directly:
314
-
315
- ```typescript
316
- // Correct
317
- import {useGetYourRouteQuery} from "@/store/openApiSdk";
318
- const {data, isLoading, error} = useGetYourRouteQuery({id: "value"});
319
-
320
- // Wrong - don't use axios directly
321
- // const result = await axios.get("/api/yourRoute/value");
322
- ```
323
-
324
- ## React Best Practices (Frontend Packages)
325
-
326
- - Use functional components with `React.FC` type
327
- - Import hooks directly: `import {useEffect, useMemo} from 'react'`
328
- - Always provide return types for functions
329
- - Add explanatory comment above each `useEffect`
330
- - Wrap callbacks in `useCallback`
331
- - Prefer const arrow functions
332
- - Use inline styles over `StyleSheet.create`
333
- - Use Luxon for date operations
334
- - Place static content and interfaces at beginning of file
335
- - Minimize `use client`, `useEffect`, and `setState`
336
- - Always support React-Native Web
337
-
338
- ## CI/CD Workflows
339
-
340
- ### Required Secret Validation
341
-
342
- GitHub Actions workflows that use secrets or environment variables must validate all required variables are set before using them. Add a validation step early in the job that fails fast with a clear error message listing any missing variables.
343
-
344
- ```yaml
345
- - name: Validate required secrets
346
- run: |
347
- missing=()
348
- if [ -z "$VAR_NAME" ]; then missing+=("VAR_NAME"); fi
349
- if [ ${#missing[@]} -ne 0 ]; then
350
- echo "::error::Missing required secrets: ${missing[*]}"
351
- exit 1
352
- fi
353
- ```
354
-
355
- ## Dependency Management
356
-
357
- Uses [Bun Catalogs](https://bun.sh/docs/install/catalogs) - shared versions defined in root `package.json` under `catalog`. Reference with `catalog:` in workspace packages.
@@ -1,352 +0,0 @@
1
- # Terreno
2
-
3
- Terreno is Django/Rails for TypeScript — with universal app support.
4
-
5
- Terreno is Django/Rails for TypeScript — a batteries-included, full-stack
6
- framework where the undifferentiated 80% of an app is already written. On the
7
- backend you get Mongoose models, auto-generated REST APIs, permissions, an admin
8
- panel, authentication, and an AI service. On the frontend you get one universal
9
- app — a single React Native codebase that ships to iOS, Android, and web. It is
10
- built to be driven by AI coding agents from the first prompt to a production
11
- deploy.
12
-
13
- - Batteries included — auth, CRUD APIs, admin, permissions, AI, realtime,
14
- feature flags, and consent are already built, so your code is business logic.
15
- - Universal by default — one React Native codebase ships to iOS, Android, and
16
- web. Not a web framework with a mobile bolt-on.
17
- - AI-native — agents are a first-class client of the framework, not an
18
- afterthought.
19
-
20
- ## Packages
21
-
22
- - **api/** - REST API framework built on Express/Mongoose (`@terreno/api`)
23
- - **ui/** - React Native UI component library (`@terreno/ui`)
24
- - **rtk/** - Redux Toolkit Query utilities for API backends (`@terreno/rtk`)
25
- - **admin-backend/** - Admin panel backend plugin for @terreno/api (`@terreno/admin-backend`)
26
- - **admin-frontend/** - Admin panel frontend screens for @terreno/api backends (`@terreno/admin-frontend`)
27
- - **mcp-server/** - MCP server for AI assistant integration (`@terreno/mcp`, bins `terreno-mcp` / `terreno-mcp-local`)
28
- - **demo/** - Demo app for showcasing and testing UI components
29
- - **example-frontend/** - Example Expo app demonstrating full stack usage
30
- - **example-backend/** - Example Express backend using @terreno/api
31
-
32
- ## Development
33
-
34
- Uses [Bun](https://bun.sh/) as the package manager.
35
-
36
- ```bash
37
- bun install # Install dependencies
38
- bun run compile # Compile all packages
39
- bun run lint # Lint all packages
40
- bun run lint:fix # Fix lint issues
41
- bun run test # Run tests in api and ui
42
- ```
43
-
44
- ### Package-specific commands
45
-
46
- ```bash
47
- bun run api:test # Test API package
48
- bun run ui:test # Test UI package
49
- bun run demo:start # Start demo app
50
- bun run frontend:web # Start frontend example
51
- bun run backend:dev # Start backend example
52
- bun run mcp:build # Build MCP server
53
- bun run mcp:start # Start MCP server
54
- bun run admin-backend:compile # Compile admin backend
55
- bun run admin-frontend:compile # Compile admin frontend
56
- ```
57
-
58
- ## How the Packages Work Together
59
-
60
- The three core packages form a complete full-stack framework:
61
-
62
- ```
63
- BACKEND
64
- @terreno/api
65
- - Mongoose models with modelRouter -> CRUD endpoints
66
- - Built-in auth (JWT + Passport)
67
- - Automatic OpenAPI spec generation
68
- |
69
- /openapi.json
70
- |
71
- RTK Query SDK Codegen
72
- |
73
- FRONTEND
74
- @terreno/rtk
75
- - Generated hooks from OpenAPI spec
76
- - Auth slice with JWT token management
77
- - Automatic token refresh
78
- +
79
- @terreno/ui
80
- - React Native components (Box, Button, TextField, etc.)
81
- - TerrenoProvider for theming
82
- ```
83
-
84
- ### Integration Flow
85
-
86
- 1. **Backend (api)**: Define Mongoose models, use `modelRouter` to create CRUD endpoints with permissions
87
- 2. **OpenAPI Generation**: `setupServer` automatically generates `/openapi.json`
88
- 3. **SDK Codegen**: Frontend runs `bun run sdk` to generate RTK Query hooks from OpenAPI spec
89
- 4. **Frontend (rtk + ui)**: Use generated hooks with UI components for type-safe API calls
90
-
91
- ## Example Apps (Keep These Updated!)
92
-
93
- The `example-frontend/` and `example-backend/` directories serve as both documentation and integration tests. When adding features to api, ui, or rtk:
94
-
95
- 1. **Add examples** demonstrating new features
96
- 2. **Update SDK** after backend changes: `cd example-frontend && bun run sdk`
97
- 3. **Verify integration** by running both examples together
98
-
99
- ### Running the Full Stack
100
-
101
- ```bash
102
- # Terminal 1: Start backend
103
- bun run backend:dev
104
-
105
- # Terminal 2: Start frontend
106
- bun run frontend:web
107
- ```
108
-
109
- ## Code Style
110
-
111
- ### TypeScript/JavaScript
112
- - Use ES module syntax and TypeScript for all code
113
- - Prefer interfaces over types; avoid enums, use maps
114
- - Prefer const arrow functions over `function` keyword
115
- - Use descriptive variable names with auxiliary verbs (e.g., `isLoading`)
116
- - Use camelCase directories (e.g., `components/authWizard`)
117
- - Favor named exports
118
- - Use the RORO pattern (Receive an Object, Return an Object)
119
-
120
- ### Dates and Time
121
- - Always use Luxon instead of Date or dayjs
122
-
123
- ### Error Handling
124
- - Check error conditions at start of functions and return early
125
- - Limit nested if statements
126
- - Use multiline syntax with curly braces for all conditionals
127
-
128
- ### Testing
129
- - Use bun test with expect for testing
130
-
131
- ### Logging
132
- - Frontend: Use `console.info`, `console.debug`, `console.warn`, or `console.error` for permanent logs
133
- - Backend: Use `logger.info/warn/error/debug` for permanent logs
134
- - Use `console.log` only for debugging (to be removed)
135
-
136
- ### Development Practices
137
- - Don't apologize for errors: fix them
138
- - Prioritize modularity, DRY, performance, and security
139
- - Focus on readability over performance
140
- - Write complete, functional code without TODOs when possible
141
- - Comments should describe purpose, not effect
142
-
143
- ## Package Reference
144
-
145
- ### @terreno/api
146
-
147
- REST API framework providing:
148
-
149
- - **modelRouter**: Auto-generates CRUD endpoints for Mongoose models
150
- - **Permissions**: `IsAuthenticated`, `IsOwner`, `IsAdmin`, `IsAuthenticatedOrReadOnly`
151
- - **Query Filters**: `OwnerQueryFilter` for filtering list queries by owner
152
- - **setupServer**: Express server setup with auth, OpenAPI, and middleware
153
- - **APIError**: Standardized error handling
154
- - **logger**: Winston-based logging
155
-
156
- Key imports:
157
- ```typescript
158
- import {
159
- modelRouter,
160
- setupServer,
161
- Permissions,
162
- OwnerQueryFilter,
163
- APIError,
164
- logger,
165
- asyncHandler,
166
- authenticateMiddleware,
167
- } from "@terreno/api";
168
- ```
169
-
170
- #### modelRouter Usage
171
-
172
- ```typescript
173
- import {modelRouter, modelRouterOptions, Permissions} from "@terreno/api";
174
-
175
- const router = modelRouter(YourModel, {
176
- permissions: {
177
- list: [Permissions.IsAuthenticated],
178
- create: [Permissions.IsAuthenticated],
179
- read: [Permissions.IsOwner],
180
- update: [Permissions.IsOwner],
181
- delete: [], // Disabled
182
- },
183
- sort: "-created",
184
- queryFields: ["_id", "type", "name"],
185
- });
186
- ```
187
-
188
- #### Custom Routes
189
-
190
- For non-CRUD endpoints, use the OpenAPI builder:
191
-
192
- ```typescript
193
- import {asyncHandler, authenticateMiddleware, createOpenApiBuilder} from "@terreno/api";
194
-
195
- router.get("/yourRoute/:id", [
196
- authenticateMiddleware(),
197
- createOpenApiBuilder(options)
198
- .withTags(["yourTag"])
199
- .withSummary("Brief summary")
200
- .withPathParameter("id", {type: "string"})
201
- .withResponse(200, {data: {type: "object"}})
202
- .build(),
203
- ], asyncHandler(async (req, res) => {
204
- return res.json({data: result});
205
- }));
206
- ```
207
-
208
- #### API Conventions
209
-
210
- - Throw `APIError` with appropriate status codes: `throw new APIError({status: 400, title: "Message"})`
211
- - Do not use `Model.findOne` - use `Model.findExactlyOne` or `Model.findOneOrThrow`
212
- - Define statics/methods by direct assignment: `schema.methods = {bar() {}}`
213
- - All model types live in `src/modelInterfaces.ts`
214
- - In routes: `req.user` is `UserDocument | undefined`
215
- - In @terreno/api callbacks: cast with `const user = u as unknown as UserDocument`
216
-
217
- ### @terreno/ui
218
-
219
- React Native UI component library (a large component library):
220
-
221
- - **Layout**: Box, Page, ListDetailLayout, SplitPage, Card
222
- - **Forms**: TextField, SelectField, DateTimeField, CheckBox
223
- - **Display**: Text, Heading, Badge, DataTable
224
- - **Actions**: Button, IconButton, Link
225
- - **Feedback**: Spinner, Modal, Toast
226
- - **Theming**: TerrenoProvider, useTheme
227
-
228
- Key imports:
229
- ```typescript
230
- import {
231
- Box,
232
- Button,
233
- Card,
234
- Page,
235
- Text,
236
- TextField,
237
- TerrenoProvider,
238
- } from "@terreno/ui";
239
- ```
240
-
241
- #### UI Component Examples
242
-
243
- Layout with Box:
244
- ```typescript
245
- <Box direction="row" padding={4} gap={2} alignItems="center">
246
- <Text>Content</Text>
247
- <Button text="Action" />
248
- </Box>
249
- ```
250
-
251
- Buttons:
252
- ```typescript
253
- <Button
254
- text="Submit"
255
- variant="primary" // 'primary' | 'secondary' | 'outline' | 'ghost'
256
- onClick={handleSubmit}
257
- loading={isLoading}
258
- iconName="check"
259
- />
260
- ```
261
-
262
- Forms:
263
- ```typescript
264
- <TextField
265
- label="Email"
266
- value={email}
267
- onChangeText={setEmail}
268
- error={emailError}
269
- helperText="Enter a valid email"
270
- />
271
- ```
272
-
273
- Modals:
274
- ```typescript
275
- <Modal
276
- title="Confirm Action"
277
- visible={isVisible}
278
- primaryButtonText="Confirm"
279
- secondaryButtonText="Cancel"
280
- onDismiss={() => setIsVisible(false)}
281
- onPrimaryAction={handleConfirm}
282
- >
283
- <Text>Are you sure?</Text>
284
- </Modal>
285
- ```
286
-
287
- #### UI Common Pitfalls
288
-
289
- - Don't use inline styles when theme values are available
290
- - Don't use raw `View`/`Text` when `Box`/@terreno/ui `Text` are available
291
- - Don't forget loading and error states
292
- - Don't use `style` prop when equivalent props exist (`padding`, `margin`)
293
- - Never modify `openApiSdk.ts` manually
294
-
295
- ### @terreno/rtk
296
-
297
- Redux Toolkit Query integration:
298
-
299
- - **generateAuthSlice**: Creates auth reducer and middleware with JWT handling
300
- - **emptyApi**: Base RTK Query API for code generation
301
- - **Platform utilities**: Secure token storage (expo-secure-store for native, AsyncStorage for web)
302
-
303
- Key imports:
304
- ```typescript
305
- import {generateAuthSlice} from "@terreno/rtk";
306
- ```
307
-
308
- Always use generated SDK hooks - never use `axios` or `request` directly:
309
-
310
- ```typescript
311
- // Correct
312
- import {useGetYourRouteQuery} from "@/store/openApiSdk";
313
- const {data, isLoading, error} = useGetYourRouteQuery({id: "value"});
314
-
315
- // Wrong - don't use axios directly
316
- // const result = await axios.get("/api/yourRoute/value");
317
- ```
318
-
319
- ## React Best Practices (Frontend Packages)
320
-
321
- - Use functional components with `React.FC` type
322
- - Import hooks directly: `import {useEffect, useMemo} from 'react'`
323
- - Always provide return types for functions
324
- - Add explanatory comment above each `useEffect`
325
- - Wrap callbacks in `useCallback`
326
- - Prefer const arrow functions
327
- - Use inline styles over `StyleSheet.create`
328
- - Use Luxon for date operations
329
- - Place static content and interfaces at beginning of file
330
- - Minimize `use client`, `useEffect`, and `setState`
331
- - Always support React-Native Web
332
-
333
- ## CI/CD Workflows
334
-
335
- ### Required Secret Validation
336
-
337
- GitHub Actions workflows that use secrets or environment variables must validate all required variables are set before using them. Add a validation step early in the job that fails fast with a clear error message listing any missing variables.
338
-
339
- ```yaml
340
- - name: Validate required secrets
341
- run: |
342
- missing=()
343
- if [ -z "$VAR_NAME" ]; then missing+=("VAR_NAME"); fi
344
- if [ ${#missing[@]} -ne 0 ]; then
345
- echo "::error::Missing required secrets: ${missing[*]}"
346
- exit 1
347
- fi
348
- ```
349
-
350
- ## Dependency Management
351
-
352
- Uses [Bun Catalogs](https://bun.sh/docs/install/catalogs) - shared versions defined in root `package.json` under `catalog`. Reference with `catalog:` in workspace packages.