Karrio Apps - Getting Started
Karrio Apps enable developers to extend Karrioās shipping platform with custom integrations, embedded user interfaces, and powerful automation. Whether youāre building internal tools or creating apps for the marketplace, this guide will help you get started.
What are Karrio Apps?
Karrio Apps are custom integrations that can:
- Embed UI components directly in the Karrio dashboard
- Access Karrioās API with proper authentication and permissions
- Store configuration data securely with encrypted credentials
- Handle webhooks for real-time data synchronization
- Integrate with external services like e-commerce platforms, ERPs, and carriers
Quick Start
1. Create Your First App
Start by creating a simple āHello Worldā app to understand the basics:
Create a new app directory1mkdir my-karrio-app 2cd my-karrio-app 3 4# Create the app manifest 5touch manifest.ts 6touch component.tsx
Create your app manifest:
manifest.ts1import { AppManifest } from "@karrio/app-store/types"; 2 3export const manifest: AppManifest = { 4 id: "hello-world", 5 name: "Hello World", 6 version: "1.0.0", 7 description: "A simple hello world app for Karrio", 8 author: { 9 name: "Your Name", 10 email: "you@example.com", 11 }, 12 permissions: ["manage_shipments"], 13 assets: { 14 icon: "./assets/icon.svg", 15 screenshots: ["./assets/screenshot1.png"], 16 readme: "./README.md", 17 }, 18 components: { 19 main: "./component.tsx", 20 }, 21};
Create your main component:
component.tsx1import React from "react"; 2import { AppComponentProps } from "@karrio/app-store/types"; 3 4export default function HelloWorldApp({ app, context }: AppComponentProps) { 5 const { user, organization } = context; 6 7 return ( 8 <div className="p-6"> 9 <h1 className="text-2xl font-bold mb-4">Hello World!</h1> 10 <p className="text-gray-600 mb-4"> 11 Welcome to your first Karrio app, {user.full_name}! 12 </p> 13 <div className="bg-gray-50 p-4 rounded-lg"> 14 <h2 className="font-semibold mb-2">App Information</h2> 15 <ul className="text-sm space-y-1"> 16 <li> 17 <strong>App ID:</strong> {app.id} 18 </li> 19 <li> 20 <strong>Organization:</strong> {organization.name} 21 </li> 22 <li> 23 <strong>Installation ID:</strong> {app.installation.id} 24 </li> 25 </ul> 26 </div> 27 </div> 28 ); 29}
2. Install and Test Your App
Install your app through the Karrio dashboard or via API:
1mutation InstallApp { 2 install_app( 3 input: { 4 app_id: "hello-world" 5 app_type: "private" 6 access_scopes: ["manage_shipments"] 7 } 8 ) { 9 installation { 10 id 11 app_id 12 api_key 13 is_active 14 } 15 errors { 16 field 17 messages 18 } 19 } 20}
Your app will now be available in the Karrio dashboard with its own dedicated space.
App Types
Karrio supports three types of apps:
Built-in Apps
Pre-installed apps that come with Karrio. These are developed and maintained by the Karrio team.
Install a built-in app1const installation = await installApp({ 2 app_id: "shipping-optimizer", 3 app_type: "builtin", 4});
Marketplace Apps
Public apps available in the Karrio App Store. These go through a review process before being published.
Install a marketplace app1const installation = await installApp({ 2 app_id: "shopify-integration", 3 app_type: "marketplace", 4 access_scopes: ["manage_shipments", "manage_orders"], 5});
Private Apps
Custom apps built for specific organizations. These can be internal tools or custom integrations.
Install a private app with OAuth1const installation = await installApp({ 2 app_id: "custom-erp-sync", 3 app_type: "private", 4 requires_oauth: true, 5 oauth_app_data: { 6 display_name: "Custom ERP Sync", 7 launch_url: "https://your-app.com/karrio/launch", 8 redirect_uris: "https://your-app.com/karrio/callback", 9 }, 10});
App Architecture
Karrio Apps follow a structured architecture that ensures security, scalability, and maintainability:
Key Features
š Secure Authentication
- Automatic API key generation for each app installation
- OAuth2 integration for external service authentication
- JWT-based session management for embedded apps
- Encrypted credential storage
šØ Embedded UI Components
- React-based component system
- Access to Karrioās design system and UI components
- Responsive layouts that work across devices
- Real-time data updates
š API Integration
- Full access to Karrioās GraphQL and REST APIs
- Scoped permissions for fine-grained access control
- Rate limiting and request validation
- Webhook support for real-time events
āļø Configuration Management
- Secure storage of app settings and credentials
- User-friendly configuration interfaces
- Environment-specific configurations
- Automatic encryption of sensitive data
Development Workflow
1. Planning Your App
Before you start coding, consider:
- What problem does your app solve?
- What Karrio data do you need access to?
- Do you need to integrate with external services?
- Will your app have a user interface?
2. Setting Up Development
Clone the Karrio repository (for access to types and utilities)1git clone https://github.com/karrioapi/karrio.git 2 3# Install dependencies 4npm install @karrio/app-store @karrio/types 5 6# Set up your development environment 7export KARRIO_API_URL="http://localhost:8000" 8export KARRIO_API_KEY="your-dev-api-key"
3. Building Your App
Follow the modular architecture:
1my-app/ 2āāā manifest.ts # App configuration 3āāā component.tsx # Main React component 4āāā configuration.tsx # Settings interface (optional) 5āāā api/ # Server-side logic 6ā āāā webhooks.ts # Webhook handlers 7ā āāā sync.ts # Background jobs 8āāā assets/ # Static assets 9ā āāā icon.svg 10ā āāā screenshots/ 11āāā types.ts # TypeScript definitions
4. Testing and Deployment
- Test your app in a development environment
- Use the Karrio test suite for integration testing
- Deploy to staging for user acceptance testing
- Submit to the marketplace or install privately
Example Apps
Shipping Task Manager
A simple task management app for shipping operations:
1import React, { useState } from "react"; 2import { Button, Card, Badge } from "@karrio/ui"; 3 4export default function ShippingTasksApp({ app, karrio }) { 5 const [tasks, setTasks] = useState([]); 6 7 const addTask = async (title: string, priority: string) => { 8 const task = { 9 id: Date.now().toString(), 10 title, 11 priority, 12 completed: false, 13 created_at: new Date().toISOString(), 14 }; 15 16 setTasks([...tasks, task]); 17 18 // Optionally sync with external system 19 await karrio.post("/api/tasks", task); 20 }; 21 22 return ( 23 <div className="space-y-4"> 24 <div className="flex justify-between items-center"> 25 <h2 className="text-xl font-semibold">Shipping Tasks</h2> 26 <Button onClick={() => addTask("New Task", "medium")}>Add Task</Button> 27 </div> 28 29 <div className="grid gap-4"> 30 {tasks.map((task) => ( 31 <Card key={task.id} className="p-4"> 32 <div className="flex justify-between items-center"> 33 <h3 className="font-medium">{task.title}</h3> 34 <Badge variant={task.priority}>{task.priority}</Badge> 35 </div> 36 </Card> 37 ))} 38 </div> 39 </div> 40 ); 41}
E-commerce Integration
Connect Karrio with your e-commerce platform:
1export default function ShopifyIntegrationApp({ app, karrio, context }) { 2 const [connected, setConnected] = useState(false); 3 const [orders, setOrders] = useState([]); 4 5 const connectShopify = async () => { 6 // OAuth flow to connect with Shopify 7 const authUrl = await app.oauth.getAuthorizationUrl("shopify"); 8 window.location.href = authUrl; 9 }; 10 11 const syncOrders = async () => { 12 const shopifyOrders = await app.api.get("/shopify/orders"); 13 const shipments = await Promise.all( 14 shopifyOrders.map((order) => 15 karrio.createShipment({ 16 recipient: order.shipping_address, 17 parcels: order.line_items.map((item) => ({ 18 weight: item.weight, 19 description: item.title, 20 })), 21 }), 22 ), 23 ); 24 25 setOrders(shipments); 26 }; 27 28 return ( 29 <div className="space-y-6"> 30 {!connected ? ( 31 <div className="text-center py-8"> 32 <h2 className="text-xl mb-4">Connect your Shopify Store</h2> 33 <Button onClick={connectShopify}>Connect with Shopify</Button> 34 </div> 35 ) : ( 36 <div> 37 <div className="flex justify-between items-center mb-4"> 38 <h2 className="text-xl">Recent Orders</h2> 39 <Button onClick={syncOrders}>Sync Orders</Button> 40 </div> 41 42 {/* Order list and management */} 43 <OrdersList orders={orders} karrio={karrio} /> 44 </div> 45 )} 46 </div> 47 ); 48}
Next Steps
Ready to build your first Karrio app? Hereās what to explore next:
- Authentication - Learn about secure authentication methods
- Building Apps - Deep dive into app development
- App Manifest - Understand app configuration
- UI Components - Build beautiful interfaces
- API Integration - Connect with Karrioās APIs
- Examples - See more real-world examples
Support
Need help building your app? Here are some resources:
- Documentation: Comprehensive guides and API references
- Community: Join our Discord server for discussions
- GitHub: Report issues and contribute to the platform
- Support: Contact our team for enterprise support
Ready to transform shipping with custom apps? Letās build something amazing together!