DPageDPage

Custom Runtime Dependencies

By default, the SDK provides React, React Native, and common community packages. You can extend this with your own libraries, hooks, and components.

Overview

Custom runtime dependencies are defined in a special configuration file at the root of your project:

  • deps.dpage.ts (TypeScript)
  • deps.dpage.js (JavaScript)
The SDK automatically loads this file at initialization and merges your custom dependencies with the defaults.

Quick Start

1. Create the Configuration File

deps.dpage.ts
import axios from 'axios';
import { format } from 'date-fns';
import * as Lodash from 'lodash';
import MyCustomComponent from './src/components/MyCustomComponent';

const apiDeps = {
  axios,
  format,
  Lodash,
} as const;

const hookDeps = {} as const;

const componentDeps = {
  MyCustomComponent,
} as const;

const androidComponentDeps = {} as const;
const androidApiDeps = {} as const;
const iosComponentDeps = {} as const;
const iosApiDeps = {} as const;

export const customRuntimeDeps = {
  ...apiDeps,
  ...hookDeps,
  ...componentDeps,
  ...androidComponentDeps,
  ...androidApiDeps,
  ...iosComponentDeps,
  ...iosApiDeps,
};

2. Use in Dynamic Components

Your custom dependencies are now available in all dynamic components:

TSX
// Dynamic component template (from API)
function MyDynamicComponent() {
  const [data, setData] = useState(null);

  useEffect(() => {
    // axios is available from custom deps
    axios.get('https://api.example.com/data')
      .then(response => setData(response.data));
  }, []);

  return (
    <View>
      {/* format is available from custom deps */}
      <Text>{format(new Date(), 'PPP')}</Text>

      {/* MyCustomComponent is available from custom deps */}
      <MyCustomComponent data={data} />
    </View>
  );
}

Per-render Overrides (Advanced)

Use runtimeDeps in initDPage to register global dependencies available to all dynamic components. For edit mode and previews, you can override deps per render using runtimeDepsOverrides on DynamicComponent, MiniappComponent, or useDynamicComponent.

Keep overrides object identity stable

A new runtimeDepsOverrides object on every render bypasses caching and recompiles the component. Hoist it or create it with useMemo.
TSX
import React, { useMemo } from 'react';
import { MiniappComponent } from '@dpage-ai/react-native-dpage';

function MiniappPreview({ miniappId }: { miniappId: string }) {
  const editModeDeps = useMemo(
    () => ({
      Modal: InlineModal,
    }),
    []
  );

  return (
    <MiniappComponent
      miniappId={miniappId}
      runtimeDepsOverrides={editModeDeps}
    />
  );
}

Dependency Buckets

Organize your dependencies into semantic buckets for clarity and platform-specific handling:

BucketDescription
apiDepsData/utility libraries (axios, date-fns, lodash)
hookDepsReusable hooks (state machines, query hooks)
componentDepsShared React components (cross-platform)
androidComponentDepsAndroid-only views or helpers
iosComponentDepsiOS-only views or helpers

Examples

Adding an HTTP Client

deps.dpage.ts
import axios from 'axios';

const apiDeps = { axios } as const;

export const customRuntimeDeps = { ...apiDeps };
TSX
// Dynamic component
function UserProfile() {
  const [user, setUser] = useState(null);

  useEffect(() => {
    axios.get('/api/user/profile')
      .then(res => setUser(res.data));
  }, []);

  return user ? <Text>{user.name}</Text> : null;
}

Adding Custom Components

deps.dpage.ts
import CustomButton from './src/components/CustomButton';
import Card from './src/components/Card';
import Icon from './src/components/Icon';

const componentDeps = { CustomButton, Card, Icon } as const;

export const customRuntimeDeps = { ...componentDeps };
TSX
// Dynamic component
function Dashboard() {
  return (
    <Card>
      <Icon name="dashboard" />
      <Text>Welcome to Dashboard</Text>
      <CustomButton onPress={() => console.log('Pressed')}>
        Get Started
      </CustomButton>
    </Card>
  );
}

Default Runtime Dependencies

These are available by default in all dynamic components:

⚛️

React Hooks

useState, useEffect, useCallback, useMemo, useRef, useContext, and more.

📱

React Native Components

View, Text, TouchableOpacity, Pressable, ScrollView, FlatList, Image, and more.

🔧

React Native APIs

StyleSheet, Dimensions, Platform, Alert, Animated, Keyboard, and more.

🛡️

Community Libraries

SafeAreaView, useSafeAreaInsets from react-native-safe-area-context.

Babel Plugin (Optional)

Add the validation plugin to prevent duplicate imports at build time:

Terminal
yarn add -D @dpage-ai/babel-plugin-dpage
babel.config.js
module.exports = {
  presets: ['module:metro-react-native-babel-preset'],
  plugins: ['@dpage-ai/babel-plugin-dpage'],
};

API Reference

FunctionDescription
initializeRuntimeDeps(customDeps)Manually initialize runtime deps without config file
getMergedRuntimeDeps()Get all available runtime dependencies
getRuntimeDepsKeys()Get array of all available dependency keys
hasRuntimeDep(key)Check if a specific dependency is available

Best Practices

✅ Do

  • Keep custom dependencies minimal
  • Document what custom deps you're adding
  • Use the Babel plugin to catch duplicates
  • Test dynamic components locally

❌ Don't

  • Import dependencies already in defaults
  • Add large libraries unnecessarily
  • Add dependencies with version conflicts
  • Modify deps.dpage without testing

Troubleshooting