Getting Started With Replit

We'll build the complete app using Replit, then add native mobile features like push notifications and haptic feedback. We provide example prompts at every step so you can follow along or adapt them for your own projects.

What we'll build:

• A responsive to-do list web app using Replit
• Push notifications when tasks are assigned or due
• Haptic feedback when completing or deleting tasks
• A native iOS and Android app powered by Median.co

Why a to-do list? It's simple enough to build quickly but complex enough to showcase real native features. The patterns you learn apply to any mobile app, from productivity tools to social networks.

By the end, you'll have a working example and the confidence to build your own mobile apps using the same approach.

💡

Build Your Own App Instead

The prompts and patterns in this guide work for any mobile app—just adapt them to your project. We use a todo list here because it's a simple example that lets us walk through the complete process quickly. Feel free to substitute your own app idea and customize the prompts accordingly.

Step 1: Build your TODO app

Let's start by building your todo list app in Replit. Open a new Replit project and use Replit Agent to create your mobile-first todo application.

Build a mobile-first web application todo list. Add authentication for signup and sign in (including apple, google and facebook sign-in) and add a backend that stores the user data along with their todos. The todo app should have functions to add, edit and remove todos and each todo needs to have a title, description, priority (high, med, low) and a deadline (time)

What this prompt does:

• Creates a mobile-responsive todo list interface
• Sets up user authentication with multiple sign-in options (email, Apple, Google, Facebook)
• Configures a database backend to store user data and todos
• Implements CRUD operations (create, read, update, delete) for todos
• Adds todo properties: title, description, priority levels, and deadlines

After running the prompt:

Replit Agent will generate your complete todo app with authentication and database setup. You should see:

• A login/signup page with social authentication options
• A main todo list view
• Forms to add and edit todos
• Todo items displaying title, description, priority, and deadline
• Delete functionality for todos

Next: Once your app is built and deployed, you're ready to convert it to a native mobile app with our platform.

Step 2: Get your Replit app URL

The first step in your mobile app journey is simple: we need to tell Median.co where to find your web application. This requires your Replit app's public URL, the link that allows anyone on the internet to view your app.

1. Deploy Your Repl: Make sure your Repl is running. Replit automatically generates a public URL when your app is active.
2. Locate the Deployment URL: Look for the URL at the top of your Replit interface in the "Webview" panel. It will look like https://your-repl-name.your-username.repl.co.
3. Copy the URL: Save this URL—you'll paste it into the Median App Studio in the next step to begin the conversion process.

📘

Important Requirements

Your Replit app must be deployed and publicly accessible for Median.co to analyze and convert it. Make sure your Repl is running and the URL loads without requiring authentication.

Quick Check: Test your URL by opening it in a private/incognito browser window. If you can see your app without logging in, you're ready to proceed.

Note: Replit apps go to sleep when inactive. For production apps, consider upgrading to a paid Replit plan for always-on deployments, or use Replit's deployment options to ensure your app stays accessible.

Step 3: Create your app in Median App Studio

1. Access the Studio: Visit https://median.co/login or click "Sign In" via the navigation bar.
2. Initialize Your Project: Click the "Create a New App" button to start your mobile app project.
3. Connect Your Replit App: Paste the Replit app URL you copied in the previous step. This tells us where to find your web application.

Once you hit enter, our platform springs into action, automatically analyzing your site's structure, detecting mobile compatibility features, and generating a real-time preview across multiple device simulators. You'll instantly see how your Replit app will look and behave on actual iOS and Android devices.

Step 4: Configure basic app settings

No one-size-fits-all templates here. You can completely customize your app. In the App Studio, navigate through the sidebar tabs:

• App Name: Set the name that will appear under your app icon.
• Branding: Upload your App Icon (what users see on their home screen) and Splash Screen (what users see when the app opens).
• Navigation: Configure native UI elements like a top navigation bar or a tab menu. These complement your web content and make your app feel truly native.

Step 5: Install the Median JavaScript Bridge

To add native mobile features like push notifications and haptic feedback, you'll need the Median JavaScript Bridge. This powerful API connects your web app to native device features.

Why this matters

While your web app will work perfectly fine with our conversion, adding native features creates an experience that rivals apps built specifically for mobile platforms. Think haptic feedback when users tap buttons, access to the device camera for profile photos, or push notifications that keep users engaged.

Adding the JavaScript Bridge

1. Open Your Replit Project: Navigate to the project you want to enhance with native features.
2. Access Replit Agent: Open Replit's AI assistant.
3. Install the JavaScript Bridge: Use this simple prompt to add the Median JavaScript library to your project:

Please add the Median JavaScript library to this project. I plan to use Median.co to convert this web app into iOS and Android Mobile Apps. Install the median-js-bridge npm package and import it in the appropriate files.

Replit Agent will install the median-js-bridge package and add the necessary imports to your code. You can verify this by checking your package.json file in the file explorer.

import { useEffect, useState } from 'react';
import Median from 'median-js-bridge';

export const useMedian = () => {
  const [isReady, setIsReady] = useState(false);
  const [isNativeApp, setIsNativeApp] = useState(false);
  const [platform, setPlatform] = useState<'web' | 'android' | 'ios'>('web');

  useEffect(() => {
    // Check if running in native app
    const nativeApp = Median.isNativeApp();
    setIsNativeApp(nativeApp);

    // Initialize Median when ready
    Median.onReady(async () => {
      setIsReady(true);
      
      // Get platform info
      try {
        const currentPlatform = await Median.getPlatform();
        setPlatform(currentPlatform);
      } catch (error) {
        console.log('Platform detection error:', error);
      }
    });
  }, []);

  // Basic utility functions
  const showAlert = (message: string) => {
    if (isNativeApp && isReady) {
      // Use native alert if available, fallback to web alert
      try {
        // This is a fallback - specific API methods may vary
        window.alert(message);
      } catch (error) {
        window.alert(message);
      }
    } else {
      window.alert(message);
    }
  };

  const openUrl = (url: string) => {
    if (isNativeApp && isReady) {
      // For native app, let the system handle the URL
      window.location.href = url;
    } else {
      window.open(url, '_blank');
    }
  };

  return {
    isReady,
    isNativeApp,
    platform,
    showAlert,
    openUrl,
    Median, // Expose the raw Median object for advanced usage
  };
};

import React from "react";
import { Toaster } from "@/components/ui/toaster";
import { Toaster as Sonner } from "@/components/ui/sonner";
import { TooltipProvider } from "@/components/ui/tooltip";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { BrowserRouter, Routes, Route } from "react-router-dom";
import { AuthProvider } from "@/contexts/AuthContext";
import { useMedian } from "@/hooks/useMedian";
import Index from "./pages/Index";
import Auth from "./pages/Auth";
import NotFound from "./pages/NotFound";

const queryClient = new QueryClient();

const AppContent = () => {
  const { isReady, isNativeApp, showAlert } = useMedian();

  // Show ready notification for native apps
  React.useEffect(() => {
    if (isReady && isNativeApp) {
      console.log("Median app ready! Platform:", isNativeApp ? "Native" : "Web");
    }
  }, [isReady, isNativeApp]);

  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Index />} />
        <Route path="/auth" element={<Auth />} />
        {/* ADD ALL CUSTOM ROUTES ABOVE THE CATCH-ALL "*" ROUTE */}
        <Route path="*" element={<NotFound />} />
      </Routes>
    </BrowserRouter>
  );
};

❗️

IMPORTANT: Configure NPM package settings in App Studio

After Replit Agent installs the median-js-bridge package, you must update your settings in Median App Studio to prevent conflicts:

Why this matters: By default, Median App Studio automatically injects the JavaScript Bridge into your app. However, since you've now added it as an NPM package in your Replit project, the bridge will be included in your web app's code. Having both would cause conflicts.

What to do:

1. Log in to the Median App Studio.
2. Navigate to your app and click Web Overrides.
3. Navigate to the JavaScript Frameworks and NPM section and select Enable from the dropdown list.
4. Save your changes.

This tells Median: "Don't inject the JavaScript Bridge—my web app already includes it via NPM."

For detailed configuration instructions, see our NPM Package Documentation.

Once Replit Agent installs the library, you'll have access to dozens of native mobile features. In the following sections, we'll show you exactly which prompts to use to add specific functionality like push notifications and haptic feedback.

Step 6: Detect mobile app usage

Before adding any native feature, your app must know when it's running inside the native mobile app versus a standard web browser.

Why detection matters

Native features only work inside of your mobile app. If you (or Replit Agent) try to call a native feature like median.camera.takePicture() in a web browser, it will fail and likely crash your app.

Detection lets you safely:

• Show or hide mobile-only buttons and features
• Provide different experiences for web users (like a standard file upload)
• Call our native APIs without errors

Prompt Replit Agent to add detection

To get started, open Replit Agent. Use the following prompt, which specifically requests the officially recommended detection method.

I am using Median.co to turn this web app into a native mobile app.

Please create a global JavaScript helper variable or function named `isMedianApp`. This helper should check if `navigator.userAgent.indexOf('median') > -1`.

I will use this variable to conditionally show mobile-only features.

What Replit Agent will implement

Replit Agent will add detection code that looks similar to this.

// Detect if running in Median mobile app (Official Method)
const isMedianApp = navigator.userAgent.indexOf('median') > -1;

// You can now use this variable throughout your app
if (isMedianApp) {
  // Show mobile-only features
  // Call Median JavaScript Bridge APIs
  console.log('Running inside a Median native app!');
} else {
  // Show web-only features
  // Use web APIs instead
  console.log('Running in a web browser.');
}

Test your detection

1. Open your Replit app in your normal desktop web browser.
2. Open the developer console. You should see the message: isMedianApp = false (or your console log "Running in a web browser.").
3. Build a test version of your app in the Median App Studio.
4. Open your app in the Median simulator or on your mobile device.
5. Check the remote console. You should see: isMedianApp = true (or "Running inside a Median native app!").

Once detection works, you're ready to add other native features.

What's next?

Congratulations! You've built your todo app, set it up in the Median App Studio, and installed the JavaScript Bridge. Now you're ready to add powerful native mobile features.

Continue your journey

Follow these guides to enhance your todo app with native features: