[RFC] next.js integration

[aulneau]

I've started prototyping out a new integration that folks will be able to use when building next.js stacks apps. Please feel free to give any feedback!

Note: this is a draft implementation, it is not live on NPM yet.

---

Building out a Stacks app with next.js

The first thing you'll want to do is install the dependencies required:

yarn add micro-stacks jotai jotai-query-toolkit react-query

Getting started

To start out, micro-stacks/nextjs exports a higher order component (HoC) that we must use to wrap each next.js page.
This is important because it allows us to set certain values automatically, such as a users session or other state
elements. To get started, see the code snippet below:

// with-micro-stacks.ts
import {wrapWithMicroStacks} from 'micro-stacks/nextjs';
import type {AuthOptions} from 'micro-stacks/nextjs';

// These values tell micro-stacks what information 
// to send to the Stacks Wallet that the user 
// will use to authenticate with.
const authOptions: AuthOptions = {
    appDetails: {
        name: 'test app',
        icon: 'icon',
    },
};

// This is the higher order component that we can use to wrap each of our next.js pages. 
// NOTE: This should ONLY wrap a top-level next.js page, no other components.
export const withMicroStacks = wrapWithMicroStacks({
    authOptions
});

With our withMicroStacks higher order component defined, we can use it to wrap our example page:

import type {NextPage} from "next";
// what we've defined in the code snippet above
import {withMicroStacks} from './with-micro-stacks.ts'

const HomePage = (): NextPage<any> => {
    return <>Homepage</>
}

export default withMicroStacks(HomePage);

Authentication

Adding authentication is as straightforward as creating a button and using the methods exposed via the useAuth hook:

// wallet-connect-button.tsx
import {useAuth} from 'micro-stacks/react';

export const WalletConnectButton = () => {
    const {isSignedIn, handleSignIn, handleSignOut, isLoading} = useAuth();
    return (
        <button onClick={isSignedIn ? () => handleSignOut() : () => handleSignIn()}>
            {isLoading ? 'Loading...' : isSignedIn ? 'Sign out' : 'Connect Stacks Wallet'}
        </button>
    );
};

Adding it to our page:

import type {NextPage} from "next";
// what we've defined in the code snippet above
import {withMicroStacks} from './with-micro-stacks.ts'
import {WalletConnectButton} from './wallet-connect-button.tsx';

const HomePage = (): NextPage<any> => {
    return <><WalletConnectButton/></>
}

export default withMicroStacks(HomePage);

Fetching data

There are many helper functions that micro-stacks exports for you to use, and some novel ways that fetching Stacks
related data can be handled for you in an application that uses micro-stacks.

import type {NextPage} from "next";
import {withMicroStacks} from './with-micro-stacks.ts'
import {makeGetServerSideProps} from 'micro-stacks/nextjs'

const HomePage = (): NextPage<any> => {
    return <>Homepage</>
}
// we can select from a list of pre-defined queries 
// that will automatically fetch data for us on the server
// if the user is signed in. This provides instant data to 
// your users when they revisit or load a page with an active 
// user session.
const dataQueries = [
    'currentAccountTransactions',
    'currentAccountBalances',
    'currentAccountNames'
]

// makeGetServerSideProps returns a standard `getServerSideProps` that 
// is a standard method next.js exposes to fetch data on the server
// for a given page.
export const getServerSideProps = makeGetServerSideProps(dataQueries)

export default withMicroStacks(HomePage);

We can then use the hooks that are exposed via micro-stacks/react in any component that is a child of this page:

import {useCurrentAccountBalances} from "micro-stacks/react";

const UserBalances = () => {
    const [balances] = useCurrentAccountBalances();
    return <>{balances.stx.balance}</>
}

const HomePage = (): NextPage<any> => {
    return <>
        <UserBalances/>
    </>
}

Additional data fetching

There are many instances in which you'll want a combination of the built-in fetchers that micro-stacks exposes, and
unrelated data fetchers specific to your application. makeGetServerSideProps accounts for this by exposing a
standard getServerSideProps callback to be passed as the second argument. Using the same example as above, we can pass
in any extra data fetchers we like:

import {GetServerSidePropsContext} from "next";
import {useCurrentAccountBalances} from "micro-stacks/react";

// our built-in data queries from micro-stacks
const dataQueries = [
    'currentAccountTransactions',
    'currentAccountBalances',
    'currentAccountNames'
]

// the same factory as above, but with an addition of a custom `getServerSideProps`
export const getServerSideProps = makeGetServerSideProps(
    dataQueries,
    // use this as you would normally use `getServerSideProps`
    async (ctx: GetServerSidePropsContext) => {
        const data = await fetchMyData();
        return {
            props: {
                data
            }
        }
    })

const UserBalances = () => {
    const [balances] = useCurrentAccountBalances();
    return <>{balances.stx.balance}</>
}

// the props you pass along from `getServerSideProps` are included
// as normally would be to the page
const HomePage = ({data}): NextPage<{ data: any }> => {
    return <>
        <UserBalances/>
    </>
}

export default withMicroStacks(HomePage);