|
| 1 | +# Eitri-App |
| 2 | + |
| 3 | +An Eitri-App is an application developed using the Eitri platform. They are mini-applications that run inside host apps, allowing you to create rich and interactive experiences in a modular way. |
| 4 | + |
| 5 | +## What is an Eitri-App? |
| 6 | + |
| 7 | +Eitri-Apps are applications built with React that can run inside mobile apps that integrate the Eitri platform. They offer: |
| 8 | + |
| 9 | +- **Agile development**: Real-time hot-reload during development |
| 10 | +- **Componentization**: Use [Eitri Luminus](eitri-luminus.md) components to create interfaces |
| 11 | +- **Access to native resources**: Through [Eitri Bifrost](eitri-bifrost.md), access camera, GPS, and other resources |
| 12 | +- **Simplified publishing**: Manage versions and publications through [Eitri Console](https://console.eitri.tech/) |
| 13 | + |
| 14 | +## Eitri-App Structure |
| 15 | + |
| 16 | +``` |
| 17 | +my-eitri-app/ |
| 18 | +├── src/ |
| 19 | +│ ├── views/ # App screens |
| 20 | +│ │ └── Home.jsx |
| 21 | +│ ├── providers/ # Global Providers/Hooks |
| 22 | +│ └── locales/ # Internationalization files |
| 23 | +├── eitri-app.conf.js # Eitri-App configuration |
| 24 | +└── package.json |
| 25 | +``` |
| 26 | + |
| 27 | +## Creating an Eitri-App |
| 28 | + |
| 29 | +To create a new Eitri-App, use the [Eitri CLI](eitri-cli.md): |
| 30 | + |
| 31 | +```bash |
| 32 | +eitri create my-eitri-app |
| 33 | +``` |
| 34 | + |
| 35 | +## Development Cycle |
| 36 | + |
| 37 | +1. **Create**: Use `eitri create` to start a new project |
| 38 | +2. **Develop**: Use `eitri start` for development with hot-reload |
| 39 | +3. **Test**: Scan the QR Code with [Eitri Play](eitri-play.md) or integrated app |
| 40 | +4. **Publish**: Use `eitri push-version` to send to Console |
| 41 | +5. **Release**: Publish the version to the desired environment through Console |
| 42 | + |
| 43 | +## Creating Views and Components |
| 44 | + |
| 45 | +In Eitri, all screens (views) and components are built using React **functional components**. Each `.jsx` or `.js` file in the `src/views/` folder represents a screen in your app. |
| 46 | + |
| 47 | +### Basic View Structure |
| 48 | + |
| 49 | +A view must export a function as `default` that receives `props` as a parameter: |
| 50 | + |
| 51 | +```jsx |
| 52 | +import { Window, View, Text } from 'eitri-luminus' |
| 53 | + |
| 54 | +export default function Home(props) { |
| 55 | + return ( |
| 56 | + <Window> |
| 57 | + <View padding="medium"> |
| 58 | + <Text fontSize="large">Welcome to Eitri!</Text> |
| 59 | + </View> |
| 60 | + </Window> |
| 61 | + ) |
| 62 | +} |
| 63 | +``` |
| 64 | + |
| 65 | +**Requirements:** |
| 66 | + |
| 67 | +- Files with `.js` or `.jsx` extension |
| 68 | +- Export the function as `default` |
| 69 | +- Receive `props` as parameter to access navigation data |
| 70 | + |
| 71 | +### Complete Example with State and Requests |
| 72 | + |
| 73 | +```jsx |
| 74 | +import { useEffect, useState } from "react" |
| 75 | +import { Window, View, Text, Image } from "eitri-luminus" |
| 76 | +import Eitri from "eitri-bifrost" |
| 77 | + |
| 78 | +export default function Products(props) { |
| 79 | + const [products, setProducts] = useState([]) |
| 80 | + const [loading, setLoading] = useState(true) |
| 81 | + |
| 82 | + useEffect(() => { |
| 83 | + loadProducts() |
| 84 | + }, []) |
| 85 | + |
| 86 | + const loadProducts = async () => { |
| 87 | + try { |
| 88 | + const response = await Eitri.http.get( |
| 89 | + "https://api.example.com/products" |
| 90 | + ) |
| 91 | + setProducts(response.data) |
| 92 | + } catch (error) { |
| 93 | + console.error("Error loading products:", error) |
| 94 | + } finally { |
| 95 | + setLoading(false) |
| 96 | + } |
| 97 | + } |
| 98 | + |
| 99 | + if (loading) { |
| 100 | + return ( |
| 101 | + <Window> |
| 102 | + <Text>Loading...</Text> |
| 103 | + </Window> |
| 104 | + ) |
| 105 | + } |
| 106 | + |
| 107 | + return ( |
| 108 | + <Window> |
| 109 | + {products.map((product) => ( |
| 110 | + <View |
| 111 | + key={product.id} |
| 112 | + display="flex" |
| 113 | + direction="column" |
| 114 | + marginTop="medium" |
| 115 | + padding="medium" |
| 116 | + > |
| 117 | + <Image src={product.imageUrl} width={320} height={320} /> |
| 118 | + <Text fontSize="large">{product.title}</Text> |
| 119 | + <Text>{product.description}</Text> |
| 120 | + </View> |
| 121 | + ))} |
| 122 | + </Window> |
| 123 | + ) |
| 124 | +} |
| 125 | +``` |
| 126 | + |
| 127 | +### Providers and Global State |
| 128 | + |
| 129 | +Eitri does **not** use `App.tsx`. All global state must be centralized in the `providers/` folder. |
| 130 | + |
| 131 | +#### MainProvider |
| 132 | + |
| 133 | +The file `src/providers/__main__.jsx` is the main provider that wraps the entire application. Use it to centralize all other providers. |
| 134 | + |
| 135 | +**File: `src/providers/__main__.jsx`** |
| 136 | + |
| 137 | +```jsx |
| 138 | +import { createContext } from "react" |
| 139 | +import AuthProvider from "./Auth" |
| 140 | + |
| 141 | +const MainContext = createContext({}) |
| 142 | + |
| 143 | +export default function MainProvider({ children }) { |
| 144 | + return ( |
| 145 | + <MainContext.Provider value={{}}> |
| 146 | + <AuthProvider> |
| 147 | + {children} |
| 148 | + </AuthProvider> |
| 149 | + </MainContext.Provider> |
| 150 | + ) |
| 151 | +} |
| 152 | +``` |
| 153 | + |
| 154 | +#### Creating a Provider |
| 155 | + |
| 156 | +To share state between multiple views, create Providers in the `src/providers/` folder. The file must start with an uppercase letter and export the provider as `default`. |
| 157 | + |
| 158 | +**Example: `src/providers/Auth.jsx`** |
| 159 | + |
| 160 | +```jsx |
| 161 | +import { createContext, useContext, useState } from "react" |
| 162 | + |
| 163 | +const AuthContext = createContext({}) |
| 164 | + |
| 165 | +export default function AuthProvider({ children }) { |
| 166 | + const [user, setUser] = useState(null) |
| 167 | + |
| 168 | + const login = async (credentials) => { |
| 169 | + // Authentication logic |
| 170 | + const userData = await authenticateUser(credentials) |
| 171 | + setUser(userData) |
| 172 | + } |
| 173 | + |
| 174 | + const logout = () => { |
| 175 | + setUser(null) |
| 176 | + } |
| 177 | + |
| 178 | + return ( |
| 179 | + <AuthContext.Provider value={{ user, login, logout }}> |
| 180 | + {children} |
| 181 | + </AuthContext.Provider> |
| 182 | + ) |
| 183 | +} |
| 184 | + |
| 185 | +export function useAuth() { |
| 186 | + return useContext(AuthContext) |
| 187 | +} |
| 188 | +``` |
| 189 | + |
| 190 | +#### Using the Provider in a View |
| 191 | + |
| 192 | +```jsx |
| 193 | +import { useAuth } from "@/providers/Auth" |
| 194 | + |
| 195 | +export default function Profile(props) { |
| 196 | + const { user, logout } = useAuth() |
| 197 | + |
| 198 | + return ( |
| 199 | + <Window> |
| 200 | + <Text>Hello, {user?.name}</Text> |
| 201 | + <Button label="Logout" onPress={logout} /> |
| 202 | + </Window> |
| 203 | + ) |
| 204 | +} |
| 205 | +``` |
| 206 | +
|
| 207 | +!!! tip "Import with @" |
| 208 | + Use `@/` to import files from the `src/` folder, regardless of your current view's depth level. |
| 209 | +
|
| 210 | +## Navigation |
| 211 | +
|
| 212 | +Eitri uses a file-based routing system, where the folder and file structure within `src/views/` automatically defines the available routes in your Eitri-App. |
| 213 | +
|
| 214 | +### File-based Routing |
| 215 | +
|
| 216 | +Each `.js` or `.jsx` file inside the `src/views/` folder automatically becomes an accessible route in your Eitri-App. |
| 217 | +
|
| 218 | +**File structure:** |
| 219 | +
|
| 220 | +``` |
| 221 | +src/views/ |
| 222 | +├── Home.jsx → /Home |
| 223 | +├── Products.jsx → /Products |
| 224 | +├── Product/ |
| 225 | +│ └── [id].jsx → /Product/:id |
| 226 | +└── Settings/ |
| 227 | + ├── index.jsx → /Settings |
| 228 | + └── Profile.jsx → /Settings/Profile |
| 229 | +``` |
| 230 | +
|
| 231 | +**Conventions:** |
| 232 | +
|
| 233 | +- **Files at views root**: Each file becomes a route with the file name |
| 234 | +- **Folders**: Create nested route segments |
| 235 | +- **index.jsx**: Represents the root route of a folder |
| 236 | +- **[parameter]**: Creates dynamic routes with parameters |
| 237 | +
|
| 238 | +### Dynamic Routes |
| 239 | +
|
| 240 | +To use dynamic routes, follow the `[parameter]` convention in the file or folder name. |
| 241 | +
|
| 242 | +For example, for a product listing with a details page: |
| 243 | +
|
| 244 | +**File structure:** |
| 245 | +
|
| 246 | +``` |
| 247 | +src/views/ |
| 248 | +├── Product |
| 249 | +│ └── [id].jsx |
| 250 | +└── Products.jsx |
| 251 | +``` |
| 252 | +
|
| 253 | +Where `id` will be the dynamic parameter. To navigate to the product with id 12345, the route will be `/Product/12345`. |
| 254 | +
|
| 255 | +### Parameter & State Retrieval |
| 256 | +
|
| 257 | +Data must be destructured inside the component body from the `props` object. |
| 258 | +
|
| 259 | +```jsx |
| 260 | +export default function ProductDetail(props) { |
| 261 | + // URL Parameters (e.g., [id]) |
| 262 | + const { id } = props.match.params |
| 263 | + |
| 264 | + // Passed State (Navigation object) |
| 265 | + const { fromSearch } = props.location.state || {} |
| 266 | + |
| 267 | + // Logic... |
| 268 | +} |
| 269 | +``` |
| 270 | +
|
| 271 | +### Programmatic Navigation |
| 272 | +
|
| 273 | +To navigate between screens in your Eitri-App, use the `Eitri.navigation.navigate` method: |
| 274 | +
|
| 275 | +```js |
| 276 | +// Navigate to Home page |
| 277 | +Eitri.navigation.navigate({ |
| 278 | + path: "/Home", |
| 279 | +}) |
| 280 | + |
| 281 | +// Navigate to a specific product |
| 282 | +Eitri.navigation.navigate({ |
| 283 | + path: "/Product/12345", |
| 284 | +}) |
| 285 | + |
| 286 | +// Navigate with state |
| 287 | +Eitri.navigation.navigate({ |
| 288 | + path: "/Products", |
| 289 | + state: { category: "electronics" } |
| 290 | +}) |
| 291 | +``` |
| 292 | +
|
| 293 | +For more information about available navigation methods, see the [Eitri Bifrost](eitri-bifrost.md) documentation. |
| 294 | +
|
| 295 | +## Shared Eitri-Apps |
| 296 | +
|
| 297 | +Shared Eitri-Apps are Eitri-Apps that can be imported and reused by other Eitri-Apps, allowing you to create modular and shareable solutions. |
| 298 | +
|
| 299 | +For more information, see the [Multiple Shareds](../quick-guides/multiple-shared.md) tutorial. |
0 commit comments