Engage Users Instantly: Embed an Interactive Demo in your React SPA

Nick van Dyke — Thu, 09 Jan 2025 19:25:31 +0000

If a picture is worth a thousand words, then an interactive demo must be worth... a million?

Do you enjoy scrolling through buzzwords to understand an app's purpose? Probably not. And I didn't care to write all that blather for my latest passion project, Wanna. So I pursued a more interesting solution: nest my app inside its own landing page for users to explore!

This gif has 263 frames, so I guess it's worth 263,000 words

Implementation

Thanks to React's composability, we can almost simply render our root App component and call it a day:

export const InteractiveDemo = () => {
    return (
        <App />
    )
}

However, you'll run into a few problems:

The demo app's navigation will navigate the real app
The demo app will retrieve real data, which may fail or not showcase it well
It may not be obvious to users what they're looking at

Let's solve those. Wanna uses React Router v6 and Apollo GraphQL, but the concepts apply regardless of technology.

Navigation

To separate the demo app's navigation from the real app, we wrap it inside another navigation provider:

+import { MemoryRouter, UNSAFE_LocationContext } from 'react-router'

export const InteractiveDemo = () => {
    return (
+       // Hack to nest MemoryRouter inside BrowserRouter.
+       // https://github.com/remix-run/react-router/issues/7375
+       <UNSAFE_LocationContext.Provider value={null}>
+           <MemoryRouter initialEntries={['/app']}>
                <App />
+           </MemoryRouter>
+       </UNSAFE_LocationContext.Provider>
    )
}

Note we use a MemoryRouter so the browser remains on the same page while the demo navigates internally.

Data

To provide the demo app with fake data, we maintain a fake "backend" inside the client app with useState and serve it via a mock client or server (depending on implementation). It's minimally invasive to the rest of the app code, and even lets us use the demo for manual testing - very handy when iterating quickly.

I used mock-apollo-client; for REST or tRPC, you might use something like nock. They're meant for automated testing but are exactly what we need here.

First, we create a mock client whose request handlers query and mutate demo data in a way that mimicks the real backend:

import { InMemoryCache } from '@apollo/client'
import { createMockClient, createMockSubscription } from 'mock-apollo-client'
import { useMemo, useState } from 'react'
// GraphQL documents that our client sends to the real server
import GET_FRIENDS from '../../gql/getFriends.gql'
import ADD_FRIEND from '../../gql/addFriend.gql'

// Simplified example
export const useDemoClient = () => {
    const [friends, setFriends] = useState[{
        __typename: 'User',
        id: 1,
        name: 'Nick',
    }]

    // Cache should persist across clients
    const cache = useMemo(() => { 
        // Should be the same cache configuration you provide to your real Apollo client
        return new InMemoryCache() 
    }, [])

    // We need to recreate the mock client whenever the data changes
    // because it doesn't support resetting request handlers.
    const mockClient = useMemo(() => {
        const client = createMockClient({ cache })

        client.setRequestHandler(GET_FRIENDS, () => Promise.resolve({
            data: {
                friends: friends
            }
        }))
        client.setRequestHandler(ADD_FRIEND, ({ user }) => {
            setFriends((prev) => prev.concat([user]))
            return Promise.resolve({
                data: {
                    addFriend: user
                }
            })
        })

        return client
    }, [friends])

    return mockClient
}

Then just like we did with navigation, we wrap our demo in a new provider with our mock client:

+import { ApolloProvider } from '@apollo/client'

export const InteractiveDemo = () => {
+   const demoClient = useDemoClient()
    return (
+       <ApolloProvider client={demoClient}> 
            <UNSAFE_LocationContext.Provider value={null}>
                <MemoryRouter initialEntries={['/app']}>
                    <App />
                </MemoryRouter>
            </UNSAFE_LocationContext.Provider>
+       </ApolloProvider>
    )
}

If you used a mock server instead, you'd inject its URL into the demo app's real client.

Visuals

It works! Now how do we make it obvious to the user that they're viewing an interactive demo?

Wanna is mobile-first, so I chose to render the demo inside a phone frame. I used devices.css because it offers the devices I thought looked best (i.e. minimal bezel to maximize demo space). But for simplicity, here we'll use a library that supports React out-of-the-box: react-device-frameset.

Let's also use zoom to shrink the demo UI and nicely nest it inside the rest of the page. In Wanna I had to invert and account for this zoom when using <canvas> with visjs-html-nodes to draw the invitee graph, but for the most part it "just works".

+import { DeviceFrameset } from 'react-device-frameset'
+import 'react-device-frameset/styles/marvel-devices.min.css'

export const InteractiveDemo = () => {
    const demoClient = useDemoClient()
    return (
+       <DeviceFrameset 
+           device='iPhone X'
+           style={{ zoom: '70%' }}>
            <ApolloProvider client={mockClient}> 
                <UNSAFE_LocationContext.Provider value={null}>
                    <MemoryRouter initialEntries={['/app']}>
                        <App />
                    </MemoryRouter>
                </UNSAFE_LocationContext.Provider>
            </ApolloProvider>
+       </DeviceFrameset>
    )
}

Lastly, it helps to have an animation so it's clearly not a static image. For example, Wanna continually ghost-types suggestions in the activity input field.

Integration

Now that we have our InteractiveDemo component, we render it inside our landing page and we're done!