Forem: Romain Trotard

Serverless function cold start is too slow, let's dockerize our app

Romain Trotard — Wed, 28 Jun 2023 19:41:31 +0000

I developed an application that I used to deploy on Vercel.
But, to deliver the best image based on the user's device, I decided to add runtime image processing, which makes it impossible for me to deploy on edge functions.
So I tried on serverless function but cold start is really really slow. Sometimes, I would experience a 5-second delay in loading my page even though I didn't have a heavy resource load. This was mainly due to the fact that I didn't have enough traffic on my website to avoid cold starts.

Note: "Cold start" typically refers to the initial startup time of a serverless function or application when there has been no recent traffic.

The solution I found was to dockerize my application and deploy it on my own server.

Dockerfile

I won't explain what Docker is since there are numerous excellent tutorials available on the web. However, to dockerize an application, the first step is to create a Dockerfile where we specify the necessary instructions. Personally, I use Astro, so here's an example of its content:

FROM node:18.16.0 AS runtime
WORKDIR /app

COPY . .

RUN npm install
RUN npm run build

ENV HOST=0.0.0.0
ENV PORT=8888
EXPOSE 8888
CMD node ./dist/server/entry.mjs

Note: You can find this code on the astro doc Build your Astro Site with Docker.

And that's not all.

My application requires some environment variables, so let's add one named DB_URL. The first thing to do is to declare that we will receive an ARG from outside:

ARG DB_URL

Then, we pass this argument as an environment variable:

ENV DB_URL=${DB_URL}

Now, let's talk about the deployment workflow.

Deployment workflow

The deployment is done through a Github Action Workflow named deploy. I trigger this workflow each time I push to the master branch, which performs the following steps:

Get the previous version and increment it.
Build and push the Docker image.
Create a Github tag with the version and push it.
Deploy the Docker image to my server.

Get the previous version and increment it

Instead of retrieving the latest image name from my registry, I push the version as a git tag. This way, I only need to fetch the latest tag, which is much easier and more efficient. Furthermore, I know the content each docker image thanks to that.

The git command to achieve this is straightforward:

LATEST_TAG=git describe --abbrev=0 --tags

And now let's increment it. But before doing it, let's see how is structured my tag.

As I push a new version each time I push on master I decided not to use semver but just have vVersionNumber.

Note: If I have released my app manually, I would have chose to use semver, and chose the right version major / minor / patch when launching the Github Action Workflow.

To extract the number from the tag, I simply remove the leading 'v':

LATEST_VERSION=${LATEST_TAG#v}

Then, the new version is calculated by incrementing the latest version:

NEW_VERSION=$(($LATEST_VERSION+1))

Whole version step

- name: Get new version
  id: newVersion
  run: |
    PREVIOUS_VERSION=$(git describe --abbrev=0 --tags)
    echo "Previous Version: $PREVIOUS_VERSION"
    LATEST_VERSION=${LATEST_TAG#v}
    NEW_VERSION=$(($LATEST_VERSION+1))
    echo "New Version: $NEW_VERSION"
    echo "NEW_VERSION=$NEW_VERSION" >> "$GITHUB_OUTPUT"

Now it's time to build the image and push it on the registry.

Build and push docker image

I use Docker Hub as my registry, but you can use the one you prefer.
To log in to Docker Hub, I utilize the docker/login-action@v2 Github Action and retrieve my credentials from Github Secrets:

- name: Login to Docker Hub
  uses: docker/login-action@v2
  with:
    username: ${{ secrets.DOCKERHUB_USERNAME }}
    password: ${{ secrets.DOCKERHUB_TOKEN }}

I then set up Docker using docker/setup-buildx-action@v2:

- name: Set up Docker
  uses: docker/setup-buildx-action@v2

An now let's build our image thanks to docker/build-push-action@v4:

- name: Build and push Docker image
        uses: docker/build-push-action@v4
        with:
          context: .
          build-args: |
            "DB_URL=${{ secrets.DB_URL }}"
          push: true
          tags: astroApp:${{ steps.newVersion.outputs.NEW_VERSION }}

Note: As you can see, I didn't forget to pass my DB_URL env variable that I get from Github secrets.

Now that the docker image is created and pushed, I can create the git tag and push it for future releases.

Create and push git tag

The first step is to set up the git config. Personally, I've chosen to use a fake "GitHub Actions" user for this purpose:

- name: Setup git config
  run: |
    git config --local user.name "GitHub Action"
    git config --local user.email "githubAction@users.noreply.github.com"

And now I can easily create and push the tag.

- name: Create and push git tag
  run: |
    git tag v${{ steps.newVersion.outputs.NEW_VERSION }}
    git push origin v${{ steps.newVersion.outputs.NEW_VERSION }}

We are nearing the end of this workflow. Now it's time to deploy the Docker image to the server.

Deploy the docker image on my server

My server is already configured with a Docker registry, eliminating the need for logging in during the GitHub Actions workflow.

To accomplish this, I utilize the appleboy/ssh-action@v0.1.10 action, which connects to the server and performs the following steps:

Pulls the latest image.
Stops the existing container (if any).
Deletes the previous container (if any).
Runs a new container with the freshly pulled image.

- name: Deploy docker image to server
  uses: appleboy/ssh-action@v0.1.10
  with:
    host: ${{ secrets.SERVER_HOST }}
    username: ${{ secrets.SERVER_USERNAME }}
    key: ${{ secrets.SSH_PRIVATE_KEY }}
    script: |
      docker pull astroApp:${{ steps.newVersion.outputs.NEW_VERSION }}
      docker stop web || true
      docker rm web || true
      docker run -d -p 8888:8888 --restart unless-stopped --name web astroApp:${{ steps.newVersion.outputs.NEW_VERSION }}

Note: This step is not perfect, as it lacks error recovery. However, for my specific use case, this limitation is not problematic since it involves a small website. In the event of any issues during deployment, I can address them manually.

Conclusion

As I mentioned previously, while my workflow may not be perfect, it is perfectly suited for my needs. With this workflow, I have eliminated cold starts and achieved an incredibly fast First Contentful Paint. It has been a significant improvement for my website.

In the future, I may consider using Ansible to enhance the process and make it more robust. Ansible's configuration management capabilities would allow me to automate and standardize the deployment process further. This would provide better error recovery and ensure consistency across deployments.

Overall, I'm satisfied with the current workflow, but I'm always open to exploring new tools and techniques to optimize my development and deployment processes.

If you want to see the whole Github Action Workflow, you can see my gist.

Feel free to comment and provide feedback. If you'd like to stay updated, you can follow me on Twitch or visit my Website. If you appreciate my work, you can also support me by buying me a coffee using this link ☕

React routing library with Navigation API

Romain Trotard — Wed, 05 Apr 2023 17:23:50 +0000

In the previous articles, we saw what is the new Navigation API and how to make an agnostic library with it.
It's now time to connect the library with React.

Note: Thanks to the agnostic way the libray is done, we could connect it to any framework.

useSyncExternalStore

The useSyncExternalStore hook enable to subscribe to an external store.

Why would we want to manage data outside of React?

when you build an agnostic library you have to store the data outside of React.
if you build a library exclusively for React, storing the data outside of React gives you full control of when your data change and when your components render. Tanner Linsley made an interesting tweet about it:

// Detect dark theme var iframe = document.getElementById('tweet-1504854824952610818-99'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1504854824952610818&theme=dark" }

React implementation

Okay, let's make it concrete!

Thanks to the router instance created with the createBrowserRouter function we can subscribe to data changes with router.subscribe and then get data snapshot with router.data which gives use:

const state = useSyncExternalStore(
    router.subscribe,
    () => router.state,
);

We are going to put this state data in a React context to be able to access to it, anywhere in the tree below, thanks to custom hooks that we are going to make.

Note: If you want to know more about React context performances, go read my article React context, performance?.

type RouterType = ReturnType<typeof createBrowserRouter>;

const RouterDataContext =
    React.createContext<RouterState | null>(null);

function RouterProvider({
    router,
}: { router: RouterType }) {
    const state = useSyncExternalStore(
        router.subscribe,
        () => router.state
    );

    return (
        <RouterDataContext.Provider value={state}>
            {
                // If the application is not initialized yet,
                // let's show a placeholder
            }
            {state.initialized ? (
                state.matchingRoute?.component ?? null
            ) : (
                <p>Loading the application</p>
            )}
        </RouterDataContext.Provider>
    );
}

And the hook to access this context, because I'm not a big to expose the context object directly and it allows us to throw nice Error if not wrapped with the Provider:

const useRouterDataContext = () => {
    const contextValue = useContext(RouterDataContext);

    if (contextValue === null) {
        throw new Error(
            "Should put a `RouterProvider`" +
                " at the top of your application",
        );
    }

    return contextValue;
};

Getting loader data

Let's make a quick reminder of what is the loader data with some code:

const routes: Routes = [
    {
        path: "/listing",
        component: <ListingPage />,
        // It will return data returned by this function
        loader: async () => {
            const libraries = await getLibraries();

            return { libraries };
        },
    },
];

Thanks to the previous hook it's easy to build useLoaderData that allows use to get this data:

function useLoaderData<T>() {
    const state = useRouterDataContext();

    return state.loaderData as T;
}

navigate an prompt before leave features

Okay we can get the loader data but what about navigate and show a prompt before leave modal if there are some unsaved data before leaving the page.

We can get this thanks to the router instance but it's not really convenient. I propose to put theses methods directly in another context.

Note: we could also put the router instance in a context! I just restrict what is accessible.

type RouterType = ReturnType<typeof createBrowserRouter>;

type RouterContextProps = Pick<
    RouterType,
    "navigate" | "registerBlockingRoute"
>;

const RouterContext =
    React.createContext<RouterContextProps | null>(null);

function RouterProvider({
    router,
}: { router: RouterType }) {
    const state = useSyncExternalStore(
        router.subscribe,
        () => router.state,
        () => router.state,
    );

    // Expose `navigate` and `registerBlockingRoute`
    const routerContextValue = useMemo(
        () => ({
            navigate: router.navigate,
            registerBlockingRoute:
                router.registerBlockingRoute,
        }),
        [router.navigate, router.registerBlockingRoute],
    );

    return (
        <RouterContext.Provider value={routerContextValue}>
            <RouterDataContext.Provider value={state}>
                {state.initialized ? (
                    state.matchingRoute?.component ?? null
                ) : (
                    <p>Loading the application</p>
                )}
            </RouterDataContext.Provider>
        </RouterContext.Provider>
    );
}

And here is the hook to get values from this context

export const useRouterContext = () => {
    const contextValue = useContext(RouterContext);

    if (contextValue === null) {
        throw new Error(
            "Should put a `RouterProvider`" +
                " at the top of your application",
        );
    }

    return contextValue;
};

It's now time to implement our 2 hooks useNavigate and usePrompt.

useNavigate

Yep we are going to start with useNavigate implementation because it's really simple:

function useNavigate() {
    const { navigate } = useRouterContext();

    return navigate;
}

usePrompt

We want to be able to pass the following props:

the condition to display the modal
a callback to display the modal
the message to display (useful when going outside of the React application. In this case, the native browser prompt will be displayed)

// This hook will be expose by React in the future
function useEffectEvent(cb: Function) {
    const cbRef = useRef(cb);

    useLayoutEffect(() => {
        cbRef.current = cb;
    });

    return useCallback((...args) => {
        return cbRef.current(...args);
    }, []);
}

function usePrompt({
    when,
    promptUser,
    message = "Are you sure you want to leave?" +
        " You will lose unsaved changes",
}: {
    message?: string;
    when: boolean;
    promptUser: () => Promise<boolean>;
}) {
    const { registerBlockingRoute } = useRouterContext();
    const shouldPrompt = useEffectEvent(() => when);
    const promptUserEffectEvent =
        useEffectEvent(promptUser);

    useEffect(() => {
        return registerBlockingRoute({
            customPromptBeforeLeaveModal:
                promptUserEffectEvent,
            message: message,
            shouldPrompt,
        });
    }, [registerBlockingRoute, shouldPrompt]);
}

Note: If you want to know more about useEffectEvent, you can read my article useEvent: the new upcoming hook?.

And that's all?
Well, I think it's important to see the Prompt component implementation, because there is a little "trick".

To do this I will use the react-modal library that allows use to build modal that is controlled.

The backbone is:

function Prompt({
    when,
    message = "Are you sure you want to leave?" +
        " You will lose unsaved changes",
}: { when: boolean; message?: string }) {
    const [showModal, setShowModal] = useState(false);

    const promptUser = () => {
        setShowModal(true);

        // What should we return?
        // If we return Promise.resolve(true) 
        // it will be resolved directly :/
    };
    const closeModal = () => {
        setShowModal(false);
    };

    usePrompt({ when, promptUser, message });

    return (
        <Modal
            isOpen={showModal}
            onRequestClose={closeModal}
        >
            <span>Are you sure?</span>
            <span>{message}</span>
            <div>
                <button type="button" onClick={closeModal}>
                    Cancel
                </button>
                <button
                    type="button"
                    onClick={() => {
                        // How to tell to `usePrompt` that
                        // the user really wants to navigate
                        closeModal();
                    }}
                >
                    Confirm
                </button>
            </div>
        </Modal>
    );
}

There is nothing fancy here. We just control a modal to open it. But we didn't implement the promptUser totally and event handlers of both buttons too.

The navigation or not to the page is made asynchronously thanks to Promise.

If the user wants to navigate (and lose unsaved changes) we resolve this promise with true otherwise with false.

When we promptUser, let's create a Promise and store the resolve function in a React ref.

Note: If you want to know more about React ref, you can read my article Things you need to know about React ref

const promiseResolve = useRef<
    ((value: boolean) => void) | undefined
>(undefined);

const promptUser = () => {
    const promise = new Promise<boolean>((resolve) => {
        promiseResolve.current = resolve;
    });

    setShowModal(true);

    return promise;
};

And now thanks to the reference we can execute it with the right value.

const closeModal = () => {
    // Do not forget to unset the ref when closing the modal
    promiseResolve.current = undefined;
    setShowModal(false);
};

const cancelNavigationAndCloseModal = () => {
    // Resolve with false
    promiseResolve.current(false);
    closeModal();
};

const confirmNavigationAndCloseModal = () => {
    // Resolve with true
    promiseResolve.current(true);
    closeModal();
};

return (
    <Modal
        isOpen={showModal}
        onRequestClose={cancelNavigationAndCloseModal}
    >
        <span>Are you sure?</span>
        <span>{message}</span>
        <div>
            <button
                type="button"
                onClick={cancelNavigationAndCloseModal}
            >
                Cancel
            </button>
            <button
                type="button"
                onClick={confirmNavigationAndCloseModal}
            >
                Confirm
            </button>
        </div>
    </Modal>
);

Here is full code of the Prompt modal

function Prompt({
    when,
    message = "Are you sure you want to leave?" +
        " You will lose unsaved changes",
}: { when: boolean; message?: string }) {
    const [showModal, setShowModal] = useState(false);
    const promiseResolve = useRef<
        ((value: boolean) => void) | undefined
    >(undefined);

    const promptUser = () => {
        const promise = new Promise<boolean>((resolve) => {
            promiseResolve.current = resolve;
        });

        setShowModal(true);

        return promise;
    };

    usePrompt({ when, promptUser, message });

    const closeModal = () => {
        // Do not forget to unset the ref when closing the modal
        promiseResolve.current = undefined;
        setShowModal(false);
    };

    const cancelNavigationAndCloseModal = () => {
        // Resolve with false
        promiseResolve.current(false);
        closeModal();
    };

    const confirmNavigationAndCloseModal = () => {
        // Resolve with true
        promiseResolve.current(true);
        closeModal();
    };

    return (
        <Modal
            isOpen={showModal}
            onRequestClose={cancelNavigationAndCloseModal}
        >
            <span>Are you sure?</span>
            <span>{message}</span>
            <div>
                <button
                    type="button"
                    onClick={cancelNavigationAndCloseModal}
                >
                    Cancel
                </button>
                <button
                    type="button"
                    onClick={confirmNavigationAndCloseModal}
                >
                    Confirm
                </button>
            </div>
        </Modal>
    );
}

Conclusion

Thanks to the subscribe method and useSyncExternalStore we can synchronize updates of the state with React.
If you want to play with the application using this mini library you can go on the application using navigation API.
And the full code is available on my outing-lib-navigation-api repository.

Do not hesitate to comment and if you want to see more, you can follow me on Twitch or go to my Website. And here is a little link if you want to buy me a coffee ☕

Master the Art of Navigation: Building a Library with the Navigation API

Romain Trotard — Wed, 08 Feb 2023 19:36:00 +0000

In my previous article we have seen what is the new Navigation Web API.

Note: I strongly recommend you to read this article if your are not up to date on this API.

The goal is to make a really simple routing library which will be agnostic of any library/framework. And we will connect it to React in a next article.

The application we are going to build together in this series of article is the following one:

Let's get our hands dirty.

Specifications

The features we want to implement are the following:

Single Page Application
Being able to do some navigation
Implement loader data (like React Router v6 and Tanstack Router)
Prompt a modal when leaving a page with unsaved changes

How to keep things agnostic?

The idea is to implement all the logic in a createBrowserRouter function and return methods:

navigate: to do navigation inside the app
registerBlockingRoute: to block navigation (for the unsaved form use case)
state: the state of the router that will contains the matching route, the current location, the loader data, ...
subscribe: to subscribe to state changes. This is the key point of the application. Every time matching route, loader data, ... will change, then we notify subscribers of this change.

Note: We implement the observer pattern again like we have seen in the React Hook Form: a unique implementation article.

Backbone code

The first step I propose you is to implement the subscription:

type RouterState = {
    // Things to define later
};

type RouterStateSubscriber = (
    newState: RouterState,
) => void;

function createBrowserRouter() {
    let subscribers: RouterStateSubscriber[] = [];

    const subscribe = (
        subscriber: RouterStateSubscriber,
    ) => {
        subscribers.push(subscriber);

        // unsubscribe callback
        return () => {
            subscribers = subscribers.filter(
                (sub) => sub !== subscriber,
            );
        };
    };

    return {
        subscribe,
    };
}

From this, we can start implementing our features :)

Single Page Application

Simulating an SPA is really simple thanks to the new API. Because we can register a custom interceptor.

Watch out not to intercept the event if:

not possible to intercept
hash has changed
downloading a file
send form data

Note: As seen previously we put this in createBrowserRouter function.

// Code from 
// https://developer.chrome.com/docs/web-platform/navigation-api/#deciding-how-to-handle-a-navigation
function shouldNotIntercept(
    navigationEvent: NavigateEvent,
) {
    return (
        !navigationEvent.canIntercept ||
        // If this is just a hashChange,
        // just let the browser handle scrolling to the content.
        navigationEvent.hashChange ||
        // If this is a download,
        // let the browser perform the download.
        navigationEvent.downloadRequest ||
        // If this is a form submission,
        // let that go to the server.
        navigationEvent.formData
    );
}

function createBrowserRouter() {
    // Previous subscription code

    window.navigation.addEventListener(
        "navigate",
        (event) => {
            if (shouldNotIntercept(event)) {
                return;
            }

            event.intercept({
                handler: () => {
                    // Code to implement here
                },
            });
        },
    );
}

Now that we simulate an SPA, let's implement the navigation inside the application.

Navigation inside the app

Thanks to the our previous navigation interceptor you can directly use a tag to do navigation :)

<a href="/otherAppPage">Go to other app page</a>

Note: As you can see, there is no more need to preventDefault the default behavior of the browser. Because our interceptor will prevent it by default if we stay in the internal application.

What if we want to do some imperative navigation?

There are some use case where imperative navigation is needed. For example after creating an entity you probably want to go back to the listing page.

To do that we are going to implement a navigate function:

function createBrowserRouter() {
    // Previous implemented code

    const navigate = (
        url: string,
        {
            replaceMode = false,
            info,
        }: { replaceMode?: boolean; info?: any } = {},
    ) => {
        window.navigation.navigate(url, {
            history: replaceMode ? "replace" : "push",
            info,
        });
    };

    return {
        subscribe,
        navigate,
    };
}

And here we go. We rely on the navigation.navigate method and nothing else.

We now how to navigate between pages, it's now time to empower our createBrowserRouter by passing our routes.

Routes implementation

We want to pass our routes to the createBrowserRoute and calculate the matching route each time we change of location.

For the moment, a Route will have the following shape:

type Route = {
    // The pathname of the route
    path: string;
    // The content for the route
    component: JSX.Element;
};

Regarding the route matching the location, I'm not gonna handle nested routing and dynamic segments.

function getMatchingRoute(
    routes: Routes,
    pathname: string,
) {
    return (
        routes.find((route) => route.path === pathname) ??
        null
    );
}

The resulting matching route will be put in the RouterState as well as the current pathname:

type RouterState = {
    // The route matching the pathname
    matchingRoute: Route | null;
    // The current pathname
    pathname: string;
};

Note: In reality, it should be the current location instead of the pathname. With dynamic parameters but for the simplicity of the article I don't implement it here.

And the createBrowserRouter becomes:

function createBrowserRouter({
    routes,
}: { routes: Route[] }) {
    const initialPathname = window.location.pathname;

    // Previous code here

    // Easier matching method.
    // This does not handle nested routing but not 
    // the subject of the article.
    // See my `React router v6` implem article for that.
    const initialMatchingRoute = getMatchingRoute(
        routes,
        initialPathname,
    );

    let state = {
        matchingRoute: initialMatchingRoute,
        pathname: initialPathname,
    };

    return {
        // Other previous returned values
        get state() {
            return state;
        },
    };
}

Note: You've probably seen the getter of state that makes it dynamic.

We calculate the right route to display at first load of the page. But when the user is changing the location we do not handle it yet. Let's do this.

If you think we should put this code in the interceptor handler, you are totally right.

function createBrowserRouter() {
    // Previous code

    const updateState = (
        newState: Partial<RouterState>,
    ) => {
        state = { ...state, ...newState };

        // Notify to all the subscribers of the changes
        subscribers.forEach((subscriber) =>
            subscriber(state),
        );
    };

    const completeNavigation = (url: string) => {
        const { pathname } = new URL(url);

        const newMatchingRoute = getMatchingRoute(
            routes,
            pathname,
        );

        updateState({
            pathname,
            matchingRoute: newMatchingRoute,
        });
    };

    const listener = (event: NavigateEvent) => {
        if (shouldNotIntercept(event)) {
            return;
        }

        event.intercept({
            handler() {
                completeNavigation(event.destination.url);
            },
        });
    };

    // Add our interceptor
    window.navigation.addEventListener(
        "navigate",
        listener,
    );

    // Previous code
}

It's now time to implement the loaderData feature.

`loaderData` feature

Most of the time when you go on a page you will have to fetch some data from your backend.

In function of the framework you use, you have different pattern to do that. For example with React you can find:

fetch-on-render: fetch calls are made in useEffect
fetch-then-render: before rendering a page, fetch all of your data and then render the entire page at once.
render-as-you-fetch: it's like the previous pattern but render every component that has already their data available. And display a placeholder with Suspense for ones they have not.

In this article, we are going to implement the fetch-then-render strategy.

Note: It's the default behavior of Remix. But you can do render-as-you-fetch thanks to defer feature combined with Await and Suspense.

The idea is to fetch the data of the page before navigating to the new page. To do that we add a loader callback to our Route type:

type Route = {
    // The pathname of the route
    path: string;
    // The content for the route
    component: JSX.Element;
    // Your page may not need data
    loader?: () => any | Promise<any>;
};

The result of the loader will be stored in our RouterState:

type RouterState = {
    // The route matching the pathname
    matchingRoute: Route | null;
    // The current pathname
    pathname: string;
    // The data returned by `loader` callback
    loaderData: unknown;
};

Let's change a little bit our completeNavigation function to:

const noop = () => {};

const completeNavigation = async (url: string) => {
    const { pathname } = new URL(url);

    const newMatchingRoute = getMatchingRoute(
        routes,
        pathname,
    );

    const data =
        (await newMatchingRoute?.loader?.()) ?? noop();

    updateState({
        pathname,
        loaderData: data,
        matchingRoute: newMatchingRoute,
    });
};

And that's all?

Almost! We need to handle the initial loaderData. To do that, let's just initialize our first loaderData to undefined and call the completeNavigation function directly in the createBrowserRouter.

function createBrowserRouter() {
    let state: RouterState = {
        pathname: initialPathname,
        matchingRoute: initialMatchingRoute,
        loaderData: undefined,
    };

    // Previous code

    // Simulate a navigation for the first pathname.
    completeNavigation(window.location.href);

    // Next code
}

Click here to see full code

type Route = {
    // The pathname of the route
    path: string;
    // The content for the route
    component: JSX.Element;
    // Your page may not need data
    loader?: () => Promise<any> | any;
};

export type Routes = Route[];

const noop = () => undefined;

// Code from https://developer.chrome.com/docs/web-platform/navigation-api/#deciding-how-to-handle-a-navigation
function shouldNotIntercept(
    navigationEvent: NavigateEvent,
) {
    return (
        !navigationEvent.canIntercept ||
        // If this is just a hashChange,
        // just let the browser handle scrolling to the content.
        navigationEvent.hashChange ||
        // If this is a download,
        // let the browser perform the download.
        navigationEvent.downloadRequest ||
        // If this is a form submission,
        // let that go to the server.
        navigationEvent.formData
    );
}

export type RouterState = {
    // In reality should put the location.
    // With dynamic parameters, but not handle in this
    // example of implementation.
    pathname: string;
    // The route matching the pathname
    matchingRoute: Route | null;
    // The data returned by `loader` callback
    loaderData: any;
};

type RouterStateSubscriber = (
    newState: RouterState,
) => void;

function getMatchingRoute(
    routes: Routes,
    pathname: string,
) {
    return (
        routes.find((route) => route.path === pathname) ??
        null
    );
}

/**
 * This function will create the browser router state
 * It has to be called outside of any component.
 */
export default function createBrowserRouter({
    routes,
}: { routes: Routes }) {
    const initialPathname = window.location.pathname;
    let subscribers: RouterStateSubscriber[] = [];

    // Simpler matching method.
    // This does not handle nested routing but not the subject of the article.
    // See my `React router v6` implem article for that.
    const initialMatchingRoute = getMatchingRoute(
        routes,
        initialPathname,
    );

    const subscribe = (
        subscriber: RouterStateSubscriber,
    ) => {
        subscribers.push(subscriber);

        // unsubscribe callback
        return () => {
            subscribers = subscribers.filter(
                (sub) => sub !== subscriber,
            );
        };
    };

    let state: RouterState = {
        pathname: initialPathname,
        matchingRoute: initialMatchingRoute,
        loaderData: undefined,
    };

    const updateState = (
        newState: Partial<RouterState>,
    ) => {
        state = { ...state, ...newState };

        // Notify to all the subscribers of the changes
        subscribers.forEach((subscriber) =>
            subscriber(state),
        );
    };

    const completeNavigation = async (url: string) => {
        const { pathname } = new URL(url);

        const newMatchingRoute = getMatchingRoute(
            routes,
            pathname,
        );

        const data =
            (await newMatchingRoute?.loader?.()) ?? noop();

        updateState({
            pathname,
            loaderData: data,
            matchingRoute: newMatchingRoute,
        });
    };

    const listener = (event: NavigateEvent) => {
        if (shouldNotIntercept(event)) {
            return;
        }

        event.intercept({
            async handler() {
                updateState({
                    navigationInProgress: true,
                });

                await completeNavigation(
                    event.destination.url,
                );
            },
        });
    };

    // Add our interceptor
    window.navigation.addEventListener(
        "navigate",
        listener,
    );

    // Simulate a navigation for the first pathname.
    completeNavigation(window.location.href);

    const navigate = (
        url: string,
        {
            replaceMode = false,
            info,
        }: { replaceMode?: boolean; info?: any } = {},
    ) => {
        window.navigation.navigate(url, {
            history: replaceMode ? "replace" : "push",
            info,
        });
    };

    return {
        get state() {
            return state;
        },
        subscribe,
        navigate,
    };
}

When you have page with loader, if the fetching of data is long, it can take some time to change the page. Fortunately, there is the spinner of the browser that indicates that the navigation is running.

But if you want to display, your own loading state like in my application. We have to track the navigationInProgress and initialized state.

Note: The initialized state is to track when the first page is ready to be displayed. (i.e. when the data is fetched)

Of course these values are in the RouterState:

type RouterState = {
    // The route matching the pathname
    matchingRoute: Route | null;
    // The current pathname
    pathname: string;
    // The data returned by `loader` callback
    loaderData: unknown;
    // Is the first page ready to be displayed?
    initialized: boolean;
    // Is a navigation in progress?
    navigationInProgress: boolean;
};

The implementation is really easy:

function createBrowserRouter() {
    let state: RouterState = {
        pathname: initialPathname,
        matchingRoute: initialMatchingRoute,
        loaderData: undefined,
        initialized: !initialMatchingRoute?.loader,
        navigationInProgress: false,
    };

    // Previous code

    const completeNavigation = async (url: string) => {
        // Previous code

        updateState({
            pathname,
            loaderData: data,
            matchingRoute: newMatchingRoute,
            initialized: true,
            navigationInProgress: false,
        });
    };

    const listener = (event: NavigateEvent) => {
        if (shouldNotIntercept(event)) {
            return;
        }

        event.intercept({
            async handler() {
                updateState({
                    navigationInProgress: true,
                });

                await completeNavigation(
                    event.destination.url,
                );
            },
        });
    };

    // Next code
}

And here we go thanks to that, we gonna the best user experience ever :)

Let's implement our last feature: prompt before leave modal.

Prompt before leave feature

This feature is really important for the user experience. It's the feature that saves you minutes of work ruined by a miss click on a link navigation / wrong shortcut...

The use case is really simple:

the user fills a form
he doesn't save the form
go to another page
before going to the "another page" we want to prompt a modal to the user to be sure he want to leave the page without saving its form.

To implement we need two informations coming from the application:

shouldPrompt: a callback to know if we need to prompt a modal.
customPromptBeforeLeaveModal: a callback that triggers the display of a modal and return a Promise<boolean with the response of the user.

And the implementation is pretty simple:

every time an interceptable navigation is detected evaluate the shouldPrompt callback
if it's false then do nothing. Otherwise, do next steps
prevent the navigation
display the modal / execute the customPromptBeforeLeaveModal callback and wait for the response
if the result is false then we don't continue the navigation. Otherwise, let's continue the navigation with navigation.navigate function.

Note: We need to put an info while continuing the navigation to know that we must not intercept the navigation:

window.navigation.navigate(event.destination.url, {
    history: "push",
    state: event.destination.state,
    info: { forceNavigate: true, ...event.info },
});

This listener will only catch in app navigation. We need to handle:

reload of the page
going to another origin
closing tab thanks to a beforeunload listener.

Too much talk, let's see some code:

const registerBlockingRoute = ({
    shouldPrompt,
    customPromptBeforeLeaveModal,
    message = "Are you sure you want to leave? You will lose unsaved changes",
}: {
    shouldPrompt: () => boolean;
    customPromptBeforeLeaveModal: () => Promise<boolean>;
    message?: string;
}) => {
    const insideAppListener = async (
        event: NavigateEvent,
    ) => {
        // We do not intercept the navigation if:
        // - we should not
        // - if the navigation has already been catched 
        // `forceNavigate` to true in the `info`
        // - we do not should prompt
        if (
            !shouldNotIntercept(event) &&
            !event.info?.forceNavigate &&
            shouldPrompt()
        ) {
            event.preventDefault();
            const shouldContinue =
                await customPromptBeforeLeaveModal();

            // If the user wants to continue the navigation
            // and consequently loses the form data
            // let's do this
            if (shouldContinue) {
                window.navigation.navigate(
                    event.destination.url,
                    {
                        history: "push",
                        state: event.destination.state,
                        info: {
                            forceNavigate: true,
                            ...event.info,
                        },
                    },
                );
            }
        }
    };

    window.navigation.addEventListener(
        "navigate",
        insideAppListener,
    );

    const outsideAppListener = (
        event: BeforeUnloadEvent,
    ) => {
        if (shouldPrompt()) {
            event.preventDefault();
            return (event.returnValue = message);
        }
    };

    // Add event listener, for:
    // - reload of page
    // - going to other origin
    // - closing tab
    window.addEventListener(
        "beforeunload",
        outsideAppListener,
    );

    // Return unregister callback
    return () => {
        window.navigation.removeEventListener(
            "navigate",
            insideAppListener,
        );
        window.removeEventListener(
            "beforeunload",
            outsideAppListener,
        );
    };
};

The next step is to connect this implementation to your favorite library/framework :)
For me it will be React. But this adventure will be for a next article.

If you can't wait for the article you can look at my repository.

Conclusion

Nowadays, building agnostic libraries of all library/framework (React, Vue, Svelte, ...) is something that is done more and more. For example with all TanStack libraries.
Adapters are then developed to connect them to your core library.
In this article we have developed the abstraction. The magic is to expose a subscribe method to listen state changes from the adapter.
In a next article we will see how to connect it to React.

If you want to play with the application you can go to this link.

Do not hesitate to comment and if you want to see more, you can follow me on Twitch or go to my Website. And here is a little link if you want to buy me a coffee ☕

Back to the future: Navigation API

Romain Trotard — Mon, 19 Dec 2022 18:33:21 +0000

In my company's projects, I forbid to migrate our react-router to the new v6.

Why?
Because they removed the ability to block the navigation, for example when a form hasn't been saved and the user click on a link.

There is an opened issue [V6] [Feature] Getting usePrompt and useBlocker back in the router , and recently Ryan florence (one of the create of React router and Remix) commented on this and said that they removed the feature because has always had corner case where it will not work. Corner cases that will be fixed thanks to the new Navigation web API.

Let's see the innovation that introduces this new API.

Note: Currently, routing libraries like React Router, Vue Router, TanStack Router, SvelteKit Routing, ... use the history API. If you want to know more about this API you can read Let's explore javascript's Location and History API.

New NavigationHistoryEntry

Entry list

Have you ever wanted to get the list of entry in the history? I have!

Here is the use case:

You are on a article listing page
You filter by title (because only want article about the Navigation API)
Clicking on an article on the list to see the detail
You are redirected to the detail page
When you are done
You want to go back to the listing page thanks to a "Go back to listing page" button
You expect to go back to the listing page with the previous filter on year you made

With the History API it's not possible to easily do that, because you only know the number of items in the history entries.

To do the previous scenario, you have to either:

keep all the url in a global state
or only store the latest search in a global state

Both strategies suck.

Thanks to the new navigation.entries() that returns a list of NavigationHistoryEntry:

Amazing!
But this is not enough for our use case, because we can have multiple entry with the listing page url in our history.
And the user can be at any entry in the history list if playing with the "backward" / "forward" browser buttons.

For example we could have the following history entry list:

So we need to know where we are in the history entries. Fortunately, there is a new property for this. Let's see it.

More information

Each origin has its own navigation history entries.

So for example if a user navigates is on a site with the romaintrotard.com origin, all entries will be added on the list and will be visible with navigation.entries().

But if the user then goes to google.com, if we relaunch navigation.entries(), there is only one entry because a brand new list has been created for the google.com origin.

Then if the user does some backward navigation and go back to romaintrotard.com, the navigation history entries will be the previous one, so there will be more than one entry.

Current entry

Thanks to the navigation.currentEntry we can know where we are:

And now we can get our previous entry corresponding to the listing page. We just have to combine this value with the navigation.entries():

const { index } = navigation.currentEntry;
const previousEntries = navigation.entries().slice(0, index);
const matchingEntry = previousEntries.findLast((entry) => {
    // We have the `url` in the entry, let's
    // extract the `pathname`
    const url = new URL(entry.url);

    return url.pathname.startsWith("/list");
})

New way to to navigate between pages

With this new API, it will not be necessary to use the history.replaceState and history.pushState anymore but just do:

const { committed, finished } = navigation.navigate(
    "myUrl",
    options,
);

Here is a non exhaustive list of the available options:

history: defines if it is replace or push mode
state: some information to persist in the history entry

You probably wonder "Why is it better than the history API, because for now it seems to do the same things.".
And you are right.
Let's see 2 differences.

`committed` and `finished` returned values

It returns an object with two keys that can be useful when working with Single Page App:

committed: a promise that fulfills when the visible url has changed and the new entry is added in the history
finished: a promise that fulfills when all the interceptor are fulfilled

Thanks to the finished promise, you can know if the navigation has been aborted, or if the user is on the right page.

Thanks to that we can display some feedback to the user when changing of page.

<button
    type="submit"
    onClick={async () => {
        setLoading(true);

        try {
            // Send values to the back
            await submit(values);
        } catch (e) {
            showSnackbar({
                message:
                    "Sorry, an error occured " +
                    "when submitting your form.",
                status: "error",
            });
            setLoading(false);
            return;
        }

        try {
            // Then redirect to the listing page
            await navigate("/list", {
                history: push,
                info: "FromCreationPage",
                state: values,
            }).finished;
        } catch (e) {
            showSnackbar({
                message:
                    "Sorry, an error occured " +
                    "when going to the listing page.",
                status: "error",
            });
        } finally {
            setLoading(false);
        }
    }}
>
    Save
</button>

Loading feedback

Another difference with the history navigation is that the browser will display a feedback to the user on its own when the page is changing, like if we were on a Multiple Page Application.

Navigation through the entry list

We are going quickly on the new way to navigate through the NavigationHistoryEntry list.

Note: All this new methods returned the same object than navigate with committed and finished promises.

Reload of the page

Until now, you can do it thanks to location.reload(). Now, the new way will be:

const { committed, finished } = navigation.reload();

Go to the previous page

The new way to go the previous navigation history entry is to use:

const { committed, finished } = navigate.back();

The previous way to do that is with history.back().

Go to the next page

You probably already guessed it, you can also go to the next navigation history entry with:

const { committed, finished } = navigation.forward();

The previous way to do that is with history.forward().

Go to a more distant entry

Previously to go to another history entry, you will have to know the number of entry to jump. Which is not an easy way to do it, because you don't have a native way to get this information.

So you had to do a mechanism to have this value. For example by maintaining a global state with all the previous url / entry.

And then use:

history.go(delta);

History list using routing library

Note: If you use a routing library that overrides the native history API, you probably have a way to listen all the navigation:

const myLocationHistory = [];

history.listen((newLocation, action) => {
    if (action === "REPLACE") {
        myLocationHistory[myLocationHistory.length - 1] =
            newLocation;
    } else if (action === "PUSH") {
        myLocationHistory.push(newLocation);
    } else if (action === "POP") {
        myLocationHistory.pop();
    }
});

With the new Navigation Web API, there is a more straightforward way to do it with:

const { committed, finished } =
    navigation.traverseTo(entryKey);

The entryKey can be deduced thanks to the code in the "Current entry" part. Amazing!

Example of code

const { index } = navigation.currentEntry;
const previousEntries = navigation.entries().slice(0, index);
const matchingEntry = previousEntries.findLast((entry) => {
    // We have the `url` in the entry, let's
    // extract the `pathname`
    const url = new URL(entry.url);

    return url.pathname.startsWith("/list");
})

if (matchingEntry) {
    navigation.traverseTo(matchingEntry.key);
}

New NavigationEvent

You can subscribe to navigate event to be notified of all navigation event.

navigation.addEventListener("navigate", (event) => {
    console.log(
        "The new url will be:",
        event.destination.url,
    );
});

Note: The event listener can be asynchronous. In this case, the browser loading feedback will be displayed until it fulfills.

The NavigateEvent is fired for the following cases:

navigation with the location API
navigation with history API
navigation with the new navigation API
browser back and forward buttons

But will not catch:

reload of the page with the browser button
change of page if the user changes the url in the browser

For these two cases you will have to add a beforeunload event listener:

window.addEventListener("beforeunload", (event) => {
    // Do what you want
});

Blocking navigation

One of the interesting things you can do, is blocking the navigation thanks to event.preventDefault():

navigation.addEventListener("navigate", (event) => {
    if (!hasUserRight(event.destination.url)) {
                // The user 
        event.preventDefault();
    }
});

Note: It's thanks to this feature that we will be able to stop the navigation and prompt a modal when there is unsaved changed on a form.

Simulating SPA

You probably know that, routing libraries prevent the default behavior of links thanks to preventDefault. This is the way we can change the url without having a full page reload.

Note: I have an article to know the difference between stopPropagation and preventDefault: preventDefault vs stopPropagation.

It's now possible to override this default behavior for every link without preventDefault.

You just have to add an interceptor to the NavigateEvent:

navigation.addEventListener("navigate", (event) => {
    event.intercept({
        handler: () => {
            // Do some stuff, it can be async :)
            // If async, the browser will be in 
            // "loading mode" until it fulfills
        },
    });
});

Conclusion

The Navigation API brings some new ways to handle navigation and be notified of them that should simplified some tricky part in routing libraries. For example, when wanting to block the navigation when there are unsaved changes on a form.
I think this new API will replace the history one that will die slowly.
But watch out, you probably shouldn't use it right now because Firefox and Safari do not support it.

But you can play with Chrome and Edge :)
If you want to know more about it, you can read the specification.

Stay tuned, in a future article I will put all this into practice by implementing a small routing library.

Do not hesitate to comment and if you want to see more, you can follow me on Twitch or go to my Website. And here is a little link if you want to buy me a coffee ☕

React Hook Form: a unique implementation

Romain Trotard — Wed, 16 Nov 2022 20:48:06 +0000

Forms are used everyday, to login/signup, fill information when ordering something, ... It is really a masterpiece of a site.

I started making form in React with Redux Form which uses Redux to store information about forms. Yep, it was the old time where we were using Redux for everything.

Nowadays, things have changed. We have multiple libraries: Formik, React Final Form, React Hook Form, ... that most of the time uses React state to store information.

I know that some framework like Remix, encourages us to use pure html to make forms. But often, we have to use a client library if we want a nice user experience with quick feedback, or when you want complex validations on fields depending to each others.

React hook form is a library focusing on performance. Looking at its implementation is really interesting to learn some pattern that can can be used in other cases.
Let's look at what makes it unique compared to other form libraries implementations.

Prerequisites

Before starting to talk about implementation, I want to define some terms to be all on the same page:

Field: the element that collects the data from the user (input, select, datepicket, ...).
Field name: the identifier of the field.
Field value: the value filled by the user.

What would be a "simple" implementation?

If today, I have to make a form implementation. Instinctively, I would make one like Formik or React Final Form using state:

function MyForm() {
  const [values, setValues] = useState({
    firstname: "",
    lastname: "",
  });
  const onChange = (fieldName, fieldValue) => {
    setValues((prevValues) => ({
      ...prevValues,
      [fieldName]: fieldValue,
    }));
  };

  return (
    <form
      onSubmit={() => {
        // Do something with the form values
        // that are in the `values` variable
      }}
    >
      <label>
        Firstname
        <input
          type="text"
          name="firstname"
          value={values["firstname"]}
          onChange={(e) => onChange(e.target.value)}
        />
      </label>
      <label>
        Lastname
        <input
          type="text"
          name="lastname"
          value={values["lastname"]}
          onChange={(e) => onChange(e.target.value)}
        />
      </label>
      <button type="submit">Submit</button>
    </form>
  );
}

Nothing fancy here. I just store the value filled by the user in a React state. And here we go.
It's a really simplified implementation. In a real life, I would probably use a reducer because I want to store more than values: validation errors, know if the form is submitting, if fields are dirty, ...

If you want to see a more realistic implementation

// I do not handle validation and form states
// but if I do I will probably use a reducer to that 
// instead of multiple states
function useForm(initialValues = {}) {
  const [values, setValues] = useState(initialValues);

  const handleSubmit = (onSubmit) => (e) => {
    e.preventDefault();

    onSubmit(values);
  };

  const register = (fieldName) => {
    return {
      value: values[fieldName],
      onChange: (event) => {
        setValues((prevValues) => ({
          ...prevValues,
          [fieldName]: fieldValue,
        }));
      },
    };
  };

  return {
    register,
    handleSubmit,
  };
}

function MyForm() {
  const { values, onChange, handleSubmit } = useForm({
    firstname: "",
    lastname: "",
  });

  return (
    <form
      onSubmit={() => {
        // Do something with the form values
        // that are in the `values` variable
      }}
    >
      <label>
        Firstname
        <input
          type="text"
          name="firstname"
          value={values["firstname"]}
          onChange={(e) => onChange(e.target.value)}
        />
      </label>
      <label>
        Lastname
        <input
          type="text"
          name="lastname"
          value={values["lastname"]}
          onChange={(e) => onChange(e.target.value)}
        />
      </label>
      <button type="submit">Submit</button>
    </form>
  );
}

And you know what? That's not the way React Hook Form is implemented.

Key points of React Hook Form implementation

Do not use React state

The main things to know is that the library does not use React state / reducer to store the data but references.
It uses lazy initialization of React ref:

function useForm(config) {
  const formControl = useRef(undefined);

  // Lazy initialization of the React ref
  // Enter the condition only at the first render
  // (`createFormControl` returns an object
  if (formControl.current === undefined) {
    formControl.current = createFormControl(config);
  }
}

And then in the createFormControl everything is stored in const that are mutated:

function createFormControl({ initialValues }) {
  const formValues = initialValues;

  const onChange = (fieldName, fieldValue) => {
    formValues[fieldName] = fieldValue;
  };

  return {
    onChange,
  };
}

And now, it's blazingly fast because no more render.

Mmmm wait, no more render? How can we know when values are changing and state of form?

Let's see it.

Observer pattern

This pattern is really used in the industry: react-query, react-redux, ... uses it.

The principle is really simple but so powerful.
We have:

a subject: it's an object that keep track of an entity changes and notify of this change
observers: they listen to the entity changes by subscribing to the subject

If you want to see an implementation

function createSubject() {
  const listeners = [];

  const subscribe = (listener) => {
    // Add the listener
    listeners.push(listener);

    // Return an unsubscribe method
    return () => {
      listeners = listeners.filter((l) => l !== listener);
    };
  };

  const update = (value) => {
    for (const listener of listeners) {
      listener(value);
    }
  };

  return {
    subscribe,
    update,
  };
}

React Hook Form has 3 subjects:

watch: to track changes of field values
array: to track changes of field array values
state: to track changes of the form state

And now, the useWatch hook subscribe to the watch subject and update a React state when its the field that we want to track that has changed.

And here we go our component when needed.

Wait! When I want to be notified when the form is going dirty, my component does not re-render when other state values changes. How is it possible?

That's the next key point.

Proxies / defineProperty

If you don't know what is a proxy you can read my article Proxy in JS: what the hell?.

In RHF, proxies are used to know which properties of the state are used in components.

Thanks to them, we can know which properties are listened by the component and only render it when these properties are changing.

function createProxy(formState, listenedStateProps) {
  const result = {};

  // Loop on the property which are in the form state
  for (const propertyName in formState) {
    Object.defineProperty(result, {
      get() {
        // Keep in mind that the property is listened
        listenedStateProps[propertyName] = true;

        // And returns the actual value
        return formState[propertyName];
      },
    });
  }

  return result;
}

And thanks to that and the observer pattern we can update the component when listened form state properties are changed.

// control is an object that has all the logic
// and the mutated object like `_formValues`,
// `_formState`, `_subjects`, ...
function useFormState(control) {
  // At start nothing is listened
  // In reality there are more properties
  const listenedStateProps = useRef({
    isDirty: false,
    isValid: false,
  });
  // Initialize with the current `_formState` which is
  // mutated
  const [formState, setFormState] = useState(
    control._formState
  );

  useEffect(() => {
    return control._subjects.state.subscribe(
      ([stateProp, stateValue]) => {
        // If the changed property is listened let's update
        if (listenedStateProps.current[stateProp]) {
          setState((prev) => ({
            ...prev,
            [stateProp]: stateValue,
          }));
        }
      }
    );
  }, [control._subjects]);

  return createProxy(formState, listenedStateProps);
}

Stable event listener with no stale external data

Another strategy, is the usage of reference for values used in event listener that are memoized thanks to useCallback or used in useEffect.

Why?
Because we don't want to have stale data in our callback so we would have to add it in the dependency of useCallback. Because of that, it will create a brand new reference everytime the dependency is changing that does not make sense because being an event listener.

Note: it actually create a new reference at each render but the one returned by useCallback will be always the same.

Instead of that:

function MyComponent({ someData }) {
  // The reference of showData is not stable!
  const showData = useCallback(() => {
    console.log("The data is", someData);
  }, [someData]);

  return (
    <MemoizedButton type="button" onClick={showData}>
      Show the data, please
    </MemoizedButton>
  );
}

We have that:

function MyComponent({ someData }) {
  const someDataRef = useRef(someData);

  useLayoutEffect(() => {
    // Keep the reference up-to-date
    someDataRef.current = someData;
  });

  // The reference of showData is now stable!
  const showData = useCallback(() => {
    console.log("The data is", someDataRef.current);
  }, []);

  return (
    <MemoizedButton type="button" onClick={showData}>
      Show the data, please
    </MemoizedButton>
  );
}

If you have already my article useEvent: the new upcoming hook?, you probably have noticed that it's the same principle. Unfortunately, useEvent will not come soon so we would have to do that a little bit longer in our projects.

Complementary informations

In reality, in the React Hook Form codebase the implementation is not the same.

The ref is updated directly in the render, but I would not recommend you to it because can cause some trouble with new concurrent features and have inconsistency in your components.

function MyComponent({ someData }) {
  const someDataRef = useRef(someData);

  // Do not update directly in the render!!!
  someDataRef.current = someData;

  // But use a `useLayoutEffect`
  useLayoutEffect(() => {
    someDataRef.current = someData;
  });
}

That's the same pattern than the so wanted useEvent hook that will finally not to out :(

Conclusion

You should be more comfortable to browse the React Hook Form and understand the code.
Some of the key points can be used in your own codebase or if you want to develop a library.

Watch out not to too optimize your code. If you want to apply the same pattern with mutation, I recommend to mutate it everytime the data is changing and not to try to not mutate when you think it's not necessary because it can cause you some trouble when your component renders conditionally. For example I would prevent this kind of code which only mutates form state if we use the formState.isDirty on the current render, but will not work when you listen the form state dirty at the next render.

Do not hesitate to comment and if you want to see more, you can follow me on Twitch or go to my Website. And here is a little link if you want to buy me a coffee ☕

Track your test duration

Romain Trotard — Mon, 29 Aug 2022 18:36:00 +0000

Have you ever increased your test duration by upgrading some dependencies, changing a configuration, ... ?

That happened to me, and that's why I made this project that tracks the duration of each test in a project as well as the timing to run all the tests.

Note: This is a special post to show my Redis Hackathon submission

Overview of My Submission

Redis Timing Tracker will help you to track all the duration of your test. This is useful to know when your time execution suddenly increased.

All test page overview

Single test page overview

Thanks to graphs, you can easily see the evolution of timings. Each point corresponds to a run, and by clicking on it you can see the commit SHA, to look at what are the changes that has been made.

Of course, if the duration increases that doesn't mean that there is a regression, it can also be due to the add of tests. So you can see number of test executed for a run by clicking on the point.

If there is any point that complicates the read of the graph you can delete it temporarily of the graph to have a better curve or even permanently from the database.

It also detects if the current test did not run at the last execution which probably mean that it has been removed from tests.

You can see it in action: https://redis-timing-tracker.vercel.app/

Note: For now the tracking only works with Jest. And take into account only tests that don't have any error. The full test duration is not persisted if there is a test in error.

Let's see the architecture of the project:

I developed a Jest reporter that needs to be added on the project to track its execution test timing.
This reporter will publish the following data on a topic:

execution of each test
the total execution duration

Then there is a script that subscribes to that topic to process the previous messages.
For example it will store the duration for each started time on a Time Series to display the graph, the info in JSON format to get the information of each run at click. You can see all the information on the README.md.

Submission Category

I submit this project for the Wacky Wildcards.

Language Used

JS/TS/Node.js.

Link to Code

romain-trotard / redis-timing-tracker

Redis Timing Tracker

What is it?

Track the timing of your jest tests to follow the evolution of time passed for each test.

This way you can know when a change in your configuration, a library upgrade or a change in your test, increased drastically the time passed on your tests.

All test page overview

Single test page overview

The Back Office is deployed here: https://redis-timing-tracker.vercel.app/

Note: For now, it doesn't persist data of a test in error, and if there is an error it doesn't persist the full execution duration.

How it works

Here is little achitecture diagram:

Stack used

Type structures are written with Typescript.

In this project I use 3 services of the Redis Stack:

Redis pub/sub
RedisJSON
RediSearch
RedisTimeSeries

Pub/sub messages

Before looking at how the data is stored. It's important to see how Redis pub/sub is used Events are published and subscribed to a topic …

View on GitHub

Additional Resources / Info

I developped the BO with Next JS and used Chakra UI to build the frontend UI.

I used recharts to draw my graphs.

For the database, I use the node-redis client. And used the following modules:

Check out Redis OM, client libraries for working with Redis as a multi-model database.
Use RedisInsight to visualize your data in Redis.
Sign up for a free Redis database.

Javascript CLI demystified

Romain Trotard — Thu, 04 Aug 2022 19:13:21 +0000

The other day, I was adding jest to a new project. And when I add my script to run my test in the package.json, I asked myself:

How libraries can expose executable script? And how the project can use it?

Every day I use Command Line Interface, and I am sure you do too. Just look at my package.json:

{
  "scripts": {
    "lint": "eslint .",
    "test": "jest .",
    "build": "webpack ."
  }
}

A lot of libraries have CLI, jest, vitest, webpack, rollup, ...

In this article you will see that thanks to the package.json you can expose executable file.
And that, at the installation of library, the package manager creates symbolic link in a binary folder inside node_modules
to the library CLI.

Let's make a CLI together :)

Note: In the article, I will talk about npm and yarn on a UNIX machine. If you use another package manager, for example pnpm you can also
do everything I do in this article. And the command are here to help you do it. It can also act differently if you use volta for managing your version your package manager versions.

Initialization of the library

Let's make a new folder and go inside:

mkdir example-js-cli
cd example-js-cli

Now, we are going to create the package.json thanks to yarn:

yarn init

We are going to let all the values empty.

Note: You can do the same with npm by launching npm init. The final package.json will differ a little bit but not so much ;)

We end up with the following package.json:

{
  "name": "example-js-cli",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT"
}

Let's make some code

In this article, we are going to implement a simple CLI, that will print some information about your PC:

your username
the uptime of the computer
the operating system
the total memory

We are just going to use the os module of nodejs and the library chalk that allow us to make some stylized console logs easily.

Note: We can stylized console logs and do a lot of other things than console.log like console.time, console.count. If you want to know more about it
you can read my article Unknown console API in JS.

No more talking, we want some code.

Just add the chalk library:

yarn add chalk

Warning: Do not use devDependencies in a CLI! Otherwise, it will not work because the dependencies will not be added!

And here is the code, I have written:

const os = require("os");
const chalk = require("chalk");

const colors = [
  "red",
  "yellow",
  "green",
  "cyan",
  "blue",
  "magenta",
];

/**
 * Function to make some rainbow <3
 */
function rainbowText(value) {
  return value
    .split("")
    .map((letter, index) =>
      chalk[colors[index % colors.length]].bold(letter)
    )
    .join("");
}

const SECONDS_BY_HOUR = 3600;
const SECONDS_BY_DAY = SECONDS_BY_HOUR * 24;

/**
 * Seconds doesn't mean anything for me.
 * Let's transform it to day / hour / minute
 */
function secondsToHumanTime(seconds) {
  const days = Math.floor(seconds / SECONDS_BY_DAY);
  const hours = Math.floor(
    (seconds - days * SECONDS_BY_DAY) / 3600
  );
  const minutes = Math.floor(
    (seconds -
      hours * SECONDS_BY_HOUR -
      days * SECONDS_BY_DAY) /
      60
  );

  const array = [
    {
      value: days,
      label: "day",
    },
    {
      value: hours,
      label: "hour",
    },
    {
      value: minutes,
      label: "minute",
    },
  ];

  // Do not insert 0 values
  return (
    array
      .filter(({ value }) => value > 0)
      // Trick to make plural when needed
      .map(
        ({ value, label }) =>
          `${value}${label}${value > 1 ? "s" : ""}`
      )
      .join(" ")
  );
}

/**
 * Mb is way more readable for me
 */
function byteToMegaByte(byteValue) {
  return Math.floor(byteValue / Math.pow(10, 6));
}

console.log(
  `Hello ${rainbowText(os.userInfo().username)}\n`
);
console.log(
  chalk.underline(
    "Here you will some information about your pc"
  )
);

console.table([
  {
    info: "Uptime",
    value: secondsToHumanTime(os.uptime()),
  },
  {
    info: "Operating System",
    value: os.version(),
  },
  {
    info: "Total memory",
    value: `${byteToMegaByte(os.totalmem())}Mb`,
  },
]);

It's a lot of code that I give without explanation. But it should be fine to understand.

If you have some questions about it, do not hesitate to PM me on Twitter :)

And now we can run this script by running:

node index.js

This is what I get:

Otherwise, you can also add a scripts entry into our package.json:

{
  "scripts": {
    "start": "node index.js"
  }
}

And now we can just launch it with:

yarn start

But this is not the goal of this article, we want the world to use our wonderful library.

Let's make the CLI stuff

It would be wonderful if any project could just add the following scripts in their package.json:

{
  "scripts": {
    "computerInfo": "giveMeComputerInfo"
  }
}

With giveMeComputerInfo that is our CLI. Instead of located our exported scripts in their node_modules and run it with node.

As you may guess it, you will just edit your package.json to do it.

The property to do that is named bin (meaning binary).

There is two ways to reference our script.
The first one is just to put the path to your script.

{
  "bin": "./index.js"
}

In this case the name of the executable is the name of our package, i.e. example-js-cli.

Well, not the best. Here is the second method to the rescue:

{
  "bin": {
    "giveMeComputerInfo": "./index.js"
  }
}

And that's all?

Actually, no. If you add publish the library. And add it in another project, and add the scripts' entry written a bit upper on the page.
It will... just fail.

Why does it fail?

Because, we need to tell to the unix shell what is the interpreter that needs to run the script.
We can do this thanks to the following shebang syntax:

#!/usr/bin/env node

Put this at the top of the index.js file. And here we go.

How does it work?

When you add a library, the package manager will detect the property bin and will make symbolic links to each scripts
to the node_modules/.bin directory.

When a CLI is called in scripts, it will first look at the node_modules/.bin and then will look at every directory
that are registered in your PATH. For example for UNIX users, in the PATH you will find:

/usr/.bin
/usr/local/bin
...

You can all the directory, by launching:

echo $PATH

Add a package globally on your machine

You may not know, but you can also add package globally on your operating system.

You can do it with yarn with:

yarn global add theWantedPackage

And with npm:

npm install -g theWantedPackage

Then, you will be able to execute CLI of the theWantedPackage from everywhere on your computer.

How does global package work?

As you can imagine when you add a package globally, the package is installed in a node_modules somewhere on your computer and
a symbolic link will be created into /usr/local/bin/.

For example, let's add our package globally:

yarn global add example-js-cli

You can now see where is located the executable giveMeComputerInfo by launching:

which giveMeComputerInfo

Effectively, it's located in the /usr/local/bin folder, but it's only a symbolic link.

But where is the real file?

ls -l /usr/local/bin/giveNeComputerInfo

The result depends on if you use yarn or npm.

Package manager	localization
yarn	`/usr/local/lib/node_modules/bin`
npm	`/usr/local/share/.config/yarn/global/node_modules/bin`

As you can see, the symbolic link points to the symbolic link inside the node_modules/.bin folder and not directly to the script.

Fun fact: yarn create a global project that has a package.json. When you add globally a dependency it will be
added inside this package.json.

Conclusion

You can expose CLI thanks to the bin property of your package.json. It's even possible to export multiple CLI.

Then, when you install the library in a project, the package manager will detect the property and will make some symbolic link
to the .bin directory in node_modules. This symbolic link point to the real script file.

When you launch a script command, the package manager will look at the .bin folder then will look to every directory registered in your
PATH.

It's also possible to add a CLI globally on your system, in this case the library is installed in a "global" node_modules directory
and a symbolic link is created inside the /usr/local/bin folder pointer to the symbolic link inside the node_modules/.bin folder.

Do not hesitate to comment and if you want to see more, you can follow me on Twitch or go to my Website. And here is a little link if you want to buy me a coffee ☕

Exit animation with `framer-motion` demystified

Romain Trotard — Wed, 29 Jun 2022 19:07:23 +0000

Unlike Svelte which has built-in animation and transition, React does not.
If you have worked with animation in React, you probably faced the problem of not being able to animate easily a component that will unmount.

function App() {
  const [shouldShow, setShouldShow] = useState(true);

  // Do some animation when unmounting
  const onExitAnimation = ...;

  return shouldShow ? (
    <div onExit={onExitAnimation}>
      Animated when unmounting
    </div>
  ) : (
    <p>No more component</p>
  );
}

For example, when working with react-spring, you have to pass your state to the useTransition hook that will give you a new variable to use.
You can't directly condition the display of your component with the shouldShow state.
This way react-spring manages this state internally to change it when the component has finished the animation.

function App() {
  const [shouldShow, setShouldShow] = useState(true);
  const transitions = useTransition(shouldShow, {
    leave: { opacity: 0 },
  });

  return transitions(
    (styles, show) =>
      // Here we do not use directly `shouldShow`
      show && (
        <animated.div style={styles}>
          Animated when unmounting
        </animated.div>
      )
  );
}

To me it doesn't feel natural.

When I finally decided to take a look at framer-motion, it was a real pleasure when I discovered the AnimatePresence component that handles it more naturally for me.

Note: As always, the code I will write is simplified compared to the library code.

Exit animation with `framer-motion`

Let's start by looking at the code to do such animation with framer-motion.

It's pretty simple to do this animation:

import { useState } from "react";
import { AnimatePresence, motion } from "framer-motion";

export default function App() {
  const [show, setShow] = useState(true);

  return (
    <>
      <button type="button" onClick={() => setShow(!show)}>
        Show / Unshow
      </button>
      <AnimatePresence>
        {show ? (
          <motion.p exit={{ opacity: 0 }}>
            Animated content
          </motion.p>
        ) : null}
      </AnimatePresence>
    </>
  );
}

Note: I just configure the exit but you can also configure the "enter" transition thanks to intial and animate prop.

Crazy simple. But how do they manage to do this exit animation? Have you an idea? Just two words React ref :)

Under the hood

Make enter and exit animation

As you have seen in the previous example of framer-motion you can access to an object named motion. From it, you can get your animated elements on which you can use the props initial, animate and exit.

Own implementation specification

make a motion object which has a key p that returns a React component to do animation
this component have two public props named onEnter to animate when mounting and onExit to animate when unmounting
use the animation web API

Note: If you want to know more about the animation web API you can read my article Let's do some animations in native Javascript

Let's trigger the enter and exit animation thanks to an useEffect. We get the following implementation for AnimatedComponent and motion:

const AnimatedComponent =
  (Tag) =>
  ({ onExit, onEnter, ...otherProps }) => {
    const elementRef = useRef(null);

    useEffect(() => {
      const animation = elementRef.current.animate(
        onEnter,
        {
          duration: 2000,
          fill: "forwards",
        }
      );

      return () => {
        const animation = elementRef.current.animate(
          onExit,
          {
            duration: 2000,
            fill: "forwards",
          }
        );
        animation.commitStyles();
      };
      // I don't include onEnter and onExit as dependency
      // Because only want them at mount and unmount
      // Could use references to satisfy the eslint rule but
      // too much boilerplate code
    }, []);

    return <Tag {...otherProps} ref={elementRef} />;
  };

const motion = {
  p: AnimatedComponent("p"),
};

Unfortunately if we try this implementation the exit animation will not work :(

Why is it complicated to do such animation?

The reason is because when a component is no more in the React tree, it's directly removed from the DOM tree too.

How to solve this?

The idea is to trigger the animations thanks to a property isVisible.

const AnimatedComponent =
  (Tag) =>
  ({ onExit, onEnter, isVisible, ...otherProps }) => {
    const elementRef = useRef(null);

    useEffect(() => {
      if (isVisible) {
        const animation = elementRef.current.animate(
          onEnter,
          {
            duration: 2000,
            fill: "forwards",
          }
        );

        return () => animation.cancel();
      } else {
        const animation = elementRef.current.animate(
          onExit,
          {
            duration: 2000,
            fill: "forwards",
          }
        );
        animation.commitStyles();

        return () => animation.cancel();
      }
    }, [isVisible]);

    return <Tag {...otherProps} ref={elementRef} />;
  };

But we do not want the user to handle the isVisible property. Moreover the component needs to stay in the React tree to work.

It's here that comes the AnimatePresence component that will keep the unmounted children in a reference and at each render detects components that are removed.

In order to do that, we need to be able to distinguish each children components. We are going to use key for that.

Things you need to know

React.Children.forEach utility function that allows us to loop through all children
React.isValidElement function that allows us to validate that we have a React element
the key is at the first level of ReactElement and not in props!

Get all valid children

Let's do a function to get all valid children components:

function getAllValidChildren(children) {
  const validChildren = [];

  React.Children.forEach(children, (child) => {
    if (React.isValidElement(child)) {
      validChildren.push(child);
    }
  });

  return validChildren;
}

Keep children of previous render

As I said previously, we are going to keep children of the previous render thanks to React reference.

If you want to know more about the usage of React ref, you can see my article Things you need to know about React ref.

import { useRef, useLayoutEffect } from "react";

function AnimatePresence({ children }) {
  const validChildren = getAllValidChildren(children);
  const childrenOfPreviousRender = useRef(validChildren);

  useLayoutEffect(() => {
    childrenOfPreviousRender.current = validChildren;
  });
}

Get key of children and determine removed keys

Now let's write the method to get the key of a React element:

function getKey(element) {
  // I just define a default key in case the user did
  // not put one, for example if single child
  return element.key ?? "defaultKey";
}

Alright, now let's get keys of the current render and of the previous one to determine which elements have been removed:

import { useRef, useLayoutEffect } from "react";

function AnimatePresence({ children }) {
  const validChildren = getAllValidChildren(children);
  const childrenOfPreviousRender = useRef(validChildren);

  useLayoutEffect(() => {
    childrenOfPreviousRender.current = validChildren;
  });

  const currentKeys = validChildren.map(getKey);
  const previousKeys =
    childrenOfPreviousRender.current.map(getKey);
  const removedChildrenKey = new Set(
    previousKeys.filter((key) => !currentKeys.includes(key))
  );
}

Get removed elements

Now that we get keys of element that will unmount in the current render, we need to get the matching element.

To do that the easier way is to make a map of elements by key.

function getElementByKeyMap(validChildren, map) {
  return validChildren.reduce((acc, child) => {
    const key = getKey(child);
    acc[key] = child;
    return acc;
  }, map);
}

And we keep the value in a ref to preserve values at each render:

import { useRef, useLayoutEffect } from "react";

function AnimatePresence({ children }) {
  const validChildren = getAllValidChildren(children);
  const childrenOfPreviousRender = useRef(validChildren);
  const elementByKey = useRef(
    getElementByKeyMap(validChildren, {})
  );

  useLayoutEffect(() => {
    childrenOfPreviousRender.current = validChildren;
  });

  useLayoutEffect(() => {
    elementByKey.current = getElementByKeyMap(
      validChildren,
      elementByKey.current
    );
  });

  const currentKeys = validChildren.map(getKey);
  const previousKeys =
    childrenOfPreviousRender.current.map(getKey);
  const removedChildrenKey = new Set(
    previousKeys.filter((key) => !currentKeys.includes(key))
  );

  // And now we can get removed elements from elementByKey
}

It's going well!

What's going next?

As we have seen at the beginning we can't do the exit animation when unmounting the component thanks to the cleaning function in useEffect.
So we will launch this animation thanks to a boolean isVisible that will trigger

the enter animation if true
the exit one if false.

This property will be injected to the AnimatedComponent by AnimatePresence thanks to the React.cloneElement API.

So we are going to change dynamically at each render the element that are displayed:

inject isVisible={true} if always presents
inject isVisible={false} if removed

Note: We are going to introduce a new variable named childrenToRender to do that.

Injection of `isVisible` into `AnimatedComponent`

import { useRef, useLayoutEffect } from "react";

function AnimatePresence({ children }) {
  const validChildren = getAllValidChildren(children);
  const childrenOfPreviousRender = useRef(validChildren);
  const elementByKey = useRef(
    getElementByKeyMap(validChildren, {})
  );

  useLayoutEffect(() => {
    childrenOfPreviousRender.current = validChildren;
  });

  useLayoutEffect(() => {
    elementByKey.current = getElementByKeyMap(
      validChildren,
      elementByKey.current
    );
  });

  const currentKeys = validChildren.map(getKey);
  const previousKeys =
    childrenOfPreviousRender.current.map(getKey);
  const removedChildrenKey = new Set(
    previousKeys.filter((key) => !currentKeys.includes(key))
  );

  // We know that `validChildren` are visible
  const childrenToRender = validChildren.map((child) =>
    React.cloneElement(child, { isVisible: true })
  );

  // We loop through removed children to add them with
  // `isVisible` to false
  removedChildrenKey.forEach((removedKey) => {
    // We get the element thanks to the object
    // previously builded
    const element = elementByKey.current[removedKey];
    // We get the index of the element to add it
    // at the right position
    const elementIndex = previousKeys.indexOf(removedKey);

    // Add the element to the rendered children
    childrenToRender.splice(
      elementIndex,
      0,
      React.cloneElement(element, { isVisible: false })
    );
  });

  // We don't return `children` but the processed children
  return childrenToRender;
}

Oh wouah!
The animation works now but it's not totally perfect because the element stays in the tree. We need to re-render the AnimatePresence when all exit animation has been done.

We can know when an animation is ended thanks to the animation.finished promise.

`useForceRender` hook

The useForceRender hook can be done with a simple counter:

import { useState, useCallback } from "react";

function useForceRender() {
  const [_, setCount] = useState(0);

  return useCallback(
    () => setCount((prev) => prev + 1),
    []
  );
}

Re-render when all exit animation are done

The final step is to re-render the AnimatePresence component when all the exit animation are finished to render the right React elements.

After this triggered render, there will be no more the removed element in the React tree.

import { useRef, useLayoutEffect } from "react";

function AnimatePresence({ children }) {
  const forceRender = useForceRender();
  const validChildren = getAllValidChildren(children);
  const childrenOfPreviousRender = useRef(validChildren);
  const elementByKey = useRef(
    getElementByKeyMap(validChildren, {})
  );

  useLayoutEffect(() => {
    childrenOfPreviousRender.current = validChildren;
  });

  useLayoutEffect(() => {
    elementByKey.current = getElementByKeyMap(
      validChildren,
      elementByKey.current
    );
  });

  const currentKeys = validChildren.map(getKey);
  const previousKeys =
    childrenOfPreviousRender.current.map(getKey);
  const removedChildrenKey = new Set(
    previousKeys.filter((key) => !currentKeys.includes(key))
  );

  const childrenToRender = validChildren.map((child) =>
    React.cloneElement(child, { isVisible: true })
  );

  removedChildrenKey.forEach((removedKey) => {
    const element = elementByKey.current[removedKey];
    const elementIndex = previousKeys.indexOf(removedKey);

    const onExitAnimationDone = () => {
      removedChildrenKey.delete(removedKey);

      if (!removedChildrenKey.size) {
        forceRender();
      }
    };

    childrenToRender.splice(
      elementIndex,
      0,
      React.cloneElement(element, {
        isVisible: false,
        onExitAnimationDone,
      })
    );
  });

  return childrenToRender;
}

And the AnimateComponent finally becomes:

const AnimatedComponent =
  (Tag) =>
  ({
    onExit,
    onEnter,
    isVisible,
    onExitAnimationDone,
    ...otherProps
  }) => {
    const elementRef = useRef(null);

    useEffect(() => {
      if (isVisible) {
        const animation = elementRef.current.animate(
          onEnter,
          {
            duration: 2000,
            fill: "forwards",
          }
        );

        return () => animation.cancel();
      } else {
        const animation = elementRef.current.animate(
          onExit,
          {
            duration: 2000,
            fill: "forwards",
          }
        );
        animation.commitStyles();
        // When the animation has ended
        // we call `onExitAnimationDone`
        animation.finished.then(onExitAnimationDone);

        return () => animation.cancel();
      }
    }, [isVisible]);

    return <Tag {...otherProps} ref={elementRef} />;
  };

And here we go!

Conclusion

I hope I've managed to make you understand how it all works under the hood.
Actually the real implementation is not the same that I have done. They do not cloneElement but use the React context API to be able not to pass directly an animated component (motion.something).
But the main point to remember is the usage of references to get children of previous render and that the returned JSX is something processed by the AnimatePresence that manages the animation of its children and more specifically the exit one by delaying the unmount of components to see the animation.

If you have any question do not hesitate to ask me.

Do not hesitate to comment and if you want to see more, you can follow me on Twitch or go to my Website.

Virtualization with fixed size items (part 1)

Romain Trotard — Wed, 01 Jun 2022 19:13:26 +0000

Have you ever heard about virtualization? Do you know how it works under the hood?

If it's not the case or if you want to refresh your knowledge, let's do it!

Note: In this article, I only do the implementation when dealing with fixed item size. Vertical and horizontal layout will be handled.
In a second article, we will see how to manage when we have variable item height.

All the logic will be extracted in a JS class, so that you can use it in your favorite library. At the end, I do it with React.

What is virtualization?

Virtualization is the fact to put in the DOM only elements that are displayed on the user screen. In reality, there are some elements before and after to have a smooth scroll.

Why do we do that?
If you put to much elements in the DOM you can have some performance issues and a bad user experience due to:

a lot of DOM nodes in memory
style calculation and paint cost

Who uses that?
This in a technic that is really used in the industry, often in combination with infinite scroll. For example sites like Twitter, Instagram or Reddit uses it.

Note: dev.to seems not use it, which causes some trouble when we scroll a lot in the page. For example, when we have 650 articles we can see some issues:

Items with fixed height

For the first article we are going to do virtualization with items having the same height.

Before, going "deep" in the implementation, it's important to understand the strategy we gonna have.

As you can see in the image, there are multiple things to understand:

container: it's the element that will contain the list.
visible items: they are the items that are currently visible to the user. They are in blue in the image.
invisible items present in the DOM: they are extra items that are currently not visible to the user, but are present on the DOM to have a smooth scroll.
invisible items: they are items that are in the list but not present in the DOM. They will be in the DOM if they are in the range of items to put in the DOM, because are in the two previous category, when scrolling.

Get first and last index

Let's do some Maths, simple one don't be afraid, to calculate the first visible item index:

// Rounding down if the first item is half displayed
// for example
const firstVisibleIndex = Math.floor(scrollOffset / itemSize);

You see, nothing complicated. Let's do the same thing to get the last index:

// Rounding down if the last item is half displayed
// for example
const lastVisibleIndex = Math.floor(
  (scrollOffset + window.height) / itemSize
);

Extra items

Now let's talk about extra items. As seen previously, most of the time we will add extra item before and after the display ones. It will improve the smoothness of the scroll and not display big white screen when scrolling fast.

So the first index of present element is:

// We do not want to have negative index
// So let's take the max of the calculation and 0
const firstPresentIndex = Math.max(
  firstVisibleIndex - extraItems,
  0
);

And the last index of present element is:

// We do not want to have an index superior to 
// the maximum item number
// So let's take the min of the calculation and `itemNumber`
const lastPresentIndex = Math.min(
  lastVisibleIndex + extraItems,
  itemNumber
);

Positioning of items

We will need to place the items that are presents manually in the list element. The solution that I chose is to set the list element with position: relative and the items with position: absolute.

I you are not used to relative / absolute positioning, here is a little image to explain it:

For our virtualization, the items which are in absolute position, are positioned relatively to the list element (which have relative position) thanks to top or left css properties in function of the list layout.

Then the list will scroll inside the container thanks to overflow: auto.

The first thing to do is to set the list style:

const getListStyle = () => {
  const listSize = this.itemNumber * this.itemSize;

  if (this.isVerticalLayout()) {
    // When dealing with vertical layout
    // it's the height that we configure
    return {
      height: listSize,
      position: "relative",
    };
  }

  // Otherwise it's the width
  return {
    width: listSize,
    position: "relative",
  };
};

And now let's do a method to get an item style by its index:

const getItemStyle = (itemIndex) => {
  const itemPosition = itemIndex * this.itemSize;

  if (this.isVerticalLayout()) {
    // When dealing with vertical layout
    // the item is positioned with the
    // `top` property
    return {
      height: this.itemSize,
      width: "100%",
      position: "absolute",
      top: itemPosition,
    };
  }

  // Otherwise with the `left` property
  return {
    height: "100%",
    width: this.itemSize,
    position: "absolute",
    left: itemPosition,
  };
};

Full implementation in a class

Let's implement all that we have seen previously in an FixedVirtualization class:

class FixedVirtualization {
  constructor({
    containerHeight,
    containerWidth,
    itemNumber,
    itemSize,
    extraItems,
    layout,
  }) {
    this.containerHeight = containerHeight;
    this.containerWidth = containerWidth;
    this.itemNumber = itemNumber;
    this.itemSize = itemSize;
    this.extraItems = extraItems;
    this.layout = layout;
  }

  isVerticalLayout = () => {
    return this.layout === "vertical";
  };

  getListStyle = () => {
    const listSize = this.itemNumber * this.itemSize;

    if (this.isVerticalLayout()) {
      // When dealing with vertical layout
      // it's the height that we configure
      return {
        height: listSize,
        position: "relative",
      };
    }

    // Otherwise it's the width
    return {
      width: listSize,
      position: "relative",
    };
  };

  getItemStyle = (itemIndex) => {
    const itemPosition = itemIndex * this.itemSize;

    if (this.isVerticalLayout()) {
      // When dealing with vertical layout
      // the item is positioned with the
      // `top` property
      return {
        height: this.itemSize,
        width: "100%",
        position: "absolute",
        top: itemPosition,
      };
    }

    // Otherwise with the `left` property
    return {
      height: "100%",
      width: this.itemSize,
      position: "absolute",
      left: itemPosition,
    };
  };

  getFirstItemIndex = (scrollOffset) => {
    return Math.max(
      Math.floor(scrollOffset / this.itemSize) -
        this.extraItems,
      0
    );
  };

  getLastItemIndex = (scrollOffset) => {
    return Math.min(
      Math.floor(
        (scrollOffset + this.containerHeight) /
          this.itemSize
      ) + this.extraItems,
      this.itemNumber
    );
  };
}

And here we go! Only one more step before we have something fully functional.

Detects scroll

Now, we need to watch when the user is scrolling inside the container.

Let's simply add a listener on the scroll event of our container element:

// Just register an event listener on `scroll` event
// In React will be done inside a `useEffect` or 
// directly with an `onScroll` prop
const onScroll = () => {
  // Update a state or retrigger rendering of items
  // In React will be done with a `useState` to set the offset
};
container.addEventListener("scroll", onScroll);

// You will probably have to add a `removeEventListener`

Let's play

Now that we have the logic of virtualization extracted in FixedVirtualization and know that we need to re-render our items when scrolling in the container element, let's do it in React.

The API that I decided to do, is to expose a List component with the following props:

layout: the layout of our list, vertical or horizontal. By default vertical
containerHeight: the height of the container
containerWidth: the width of the container
itemNumber: the number of items that is in the list
itemSize: the size of an item. The height for vertical layout, otherwise the item width.
renderItem: a callback to render an item. The index of the item and the style to spread on the item will be passed as parameters.

This is how you will use it:

function App() {
  return (
    <List
      containerHeight={400}
      containerWidth={600}
      itemNumber={1000}
      itemHeight={50}
      renderItem={({ index, style }) => (
        <div
          key={index}
          style={{
            ...style,
            // Just put a border to see each item
            border: "1px solid black",
          }}
        >
          {index}
        </div>
      )}
    />
  );
}

And here is the implementation of the List component:

function List({
  renderItem,
  containerHeight,
  containerWidth,
  itemNumber,
  itemSize,
  layout = "vertical",
}) {
  const [fixedVirtualization] = useState(
    () =>
      new FixedVirtualization({
        containerHeight,
        itemNumber,
        itemSize,
        extraItems: 10,
        layout,
      })
  );
  // We put the offset in a state
  // And get the right items to display at each render
  // and their styles
  const [scrollOffset, setScrollOffset] = useState(0);

  const firstIndex =
    fixedVirtualization.getFirstItemIndex(scrollOffset);
  const lastIndex =
    fixedVirtualization.getLastItemIndex(scrollOffset);

  // Let's create an array of the items
  // which are present in the DOM
  const items = [];
  for (
    let index = firstIndex;
    index <= lastIndex;
    index++
  ) {
    items.push(
      renderItem({
        index,
        style: fixedVirtualization.getItemStyle(index),
      })
    );
  }

  // Let's create an `onScroll` callback
  // We `useCallback` it only to have a stable ref for
  // the throttling which is for performance reasons
  const onScroll = useCallback(
    throttle(250, (e) => {
      const { scrollTop, scrollLeft } = e.target;
      setScrollOffset(
        layout === "vertical" ? scrollTop : scrollLeft
      );
    }),
    []
  );

  return (
    <div
      style={{
        height: containerHeight,
        width: containerWidth,
        overflow: "auto",
      }}
      onScroll={onScroll}
    >
      <div style={fixedVirtualization.getListStyle()}>
        {items}
      </div>
    </div>
  );
}

Note: Here I use the throttle-debounce library.

Conclusion

You can play with the complete code with this sandbox:

In a following article, you will see how to manage when we have items with different height.

Do not hesitate to comment and if you want to see more, you can follow me on Twitch or go to my Website.

useEvent: the new upcoming hook?

Romain Trotard — Wed, 11 May 2022 16:16:13 +0000

The previous week, Dan Abramov merged a new rfc about useEvent. I propose you to look at this coming soon hook, I hope :)

Before reading this article, I recommend you to read my Things you need to know about React ref and When to use useCallback? if it's not already done.

Explanations of the problem

A first example

Have you ever felt that you add a dependency to a hook (useEffect or useCallback for example) not to have a stale closure but feeling that it's not good?

useEffect(() => {
  const twitchClient = new TwitchClient();
  twitchClient.connect();

  twitchClient.on("message", (message) => {
    if (shouldNotReadMessage) {
      console.log(`The message is: ${message}`);
    }
  });

  return () => twitchClient.disconnect();
}, [shouldNotReadMessage]);

Note: You can see me on Twitch where I do development and creative hobby.

Why I'm feeling bad about this code?

My client will disconnect / reconnect each time the shouldNotReadMessage changes, which is odd because just using it in an event listener.

So I decide to use a React ref:

const [shouldNotReadMessage, setShouldNotReadMessage] =
  useState(true);

const shouldNotReadMessageRef = useRef(
  shouldNotReadMessage
);
// Do not forget to update the reference
// This `useEffect` has to be before the next one
useEffect(() => {
  shouldNotReadMessageRef.current = shouldNotReadMessage;
});

useEffect(() => {
  const twitchClient = new TwitchClient();
  twitchClient.connect();

  twitchClient.on("message", (message) => {
    if (shouldNotReadMessageRef.current) {
      console.log(`The message is: ${message}`);
    }
  });

  return () => twitchClient.disconnect();
}, []);

No more disconnect / reconnect every time shouldNotReadMessage changes but some boilerplate code.

It's possible to make a custom hook useStateRef to mutualize the code, because it will be used often:

function useStateRef(state) {
  const ref = useRef(state);

  useLayoutEffect(() => {
    ref.current = state;
  });

  return ref;
}

Note: You will have to put the useStateRef returned value as dependency if you want to satisfy the linter.

Previous example analysis

In the previous example, the callback that needs the latest value of the state shouldNotReadMessage is an event listener. Because we want to execute the callback only when a message is received.

Most of the time, we work with event listener, their particularity is that their name can start by on. You are probably more used to deal with DOM event listener, for example when adding an onClick listener on a button.

Note: If you want to know how React handles DOM event listener you can read my article Under the hood of event listeners in React.

A second example

Have you ever deal with memoized components?

A memoized component optimizes re-render. The principle is simple: if there is no prop that has changed then the component does not render. It can be useful when dealing with component having costly renders.

Note: You can fine grained when the component should render. For example with React.memo it will be thanks to the second parameter. The default behavior is to render when any prop has changed.

So any references should be fixed.

So if you have the following code, the memoization is useless. Because each time the App renders a new onClick callback is created.

function App() {
  const onClick = () => {
    console.log("You've just clicked me");
  };

  return <MemoizedComponent onClick={onClick} />;
}

You have to use the useCallback hook.

import { useCallback } from "react";

function App() {
  const onClick = useCallback(() => {
    console.log("You've just clicked me");
  }, []);

  return <MemoizedComponent onClick={onClick} />;
}

Note: In this example I could just extract the callback outside of the component, but we are going to complexify the code soon ;)

What happened if your callback needs an external variable?

Well it depends. If you want to access a ref it's totally fine. But if it's a state you will have to add it in the array dependency of useCallback.

When this callback is an event listener then the problem is the same than before with useEffect. It seems useless to recreate a new callback each time because will make the memoized component re-render because of that.

So we will use the useStateRef hook implemented before.

Because of that you can have complex code. Trust me it happened to me :(

A last example

In my article When to use useCallback?, I tell that I try to always useCallback functions that I return from hooks that will be used in multiple places, because I don't know the place where it will be used: in useEffect? in useCallback? in event listener?
But sometimes it's complicated to make a fully fixed reference.
So it can happen, like in the previous example, that an event listener that is memoized is recreated unnecessarily.

import { useCallback, useState } from "react";

function useCalendar() {
  const [numberDayInMonth, setNumberDayInMonth] =
    useState(31);
  const [currentYear, setCurrentYear] = useState(2022);
  const [currentMonth, setCurrentMonth] =
    useState("January");

  const onNextYear = useCallback(() => {
    setCurrentYear((prevYear) => {
      const nextYear = prevYear + 1;
      if (currentMonth === "February") {
        const isLeapYear = ... // some process with nextYear

        const isLeapYear = false;
        if (isLeapYear) {
          setNumberDayInMonth(29);
        } else {
          setNumberDayInMonth(28);
        }
      }

      return nextYear;
    });
  }, [currentMonth]);

  // In a real implementation there will be much more stuffs
  return {
    numberDayInMonth,
    currentYear,
    currentMonth,
    onNextYear,
  };
}

In this case, a new callback for onNextYear will be created each time currentMonth changes.

Here again the solution would be to use the useStateRef hook implemented before.

useEvent to the rescue

The solution to all the above problems is that React exposes a new hook probably named useEvent that returns a memoized callback (with useCallback) that called the latest version of our callback.

It's quite similar to the implementation I show earlier with useStateRef but with callback.

An example of implementation would be:

function useEvent(handler) {
  const handlerRef = useRef(null);

  useLayoutEffect(() => {
    handlerRef.current = handler;
  });

  return useCallback((...args) => {
    return handlerRef.current(...args);
  }, []);
}

In reality, this will not use a useLayoutEffect because it must run before other useLayoutEffect so that they have the latest value of our callback for every case.
They will probably do an internal implementation to execute the update of the ref before all useLayoutEffect.

As a reminder, useLayoutEffect and useEffect are executed from bottom to top in the tree. Started from the bottom 🎶
So, with the implementation above, we could have a stale callback in the following code and not log the right count:

function Parent() {
  const [count, setCount] = useState(0);
  const onPathnameChange = useEvent((pathname) => {
    // Note that we use a state value
    console.log(
      "The new pathname is:",
      pathname,
      "and count:",
      count
    );
  });

  return (
    <>
      <Child onPathnameChange={onPathnameChange} />
      <button
        type="button"
        onClick={() => setCount(count + 1)}
      >
        Increment
      </button>
    </>
  );
}

function Child({ onPathnameChange }) {
  const { pathname } = useLocation();

  useLayoutEffect(() => {
    // Here we would have a stale `onPathnameChange`
    // Because this is executed before the `useEvent` one
    // So it can happen we have the previous `count` in the log
    onPathnameChange(pathname);
  }, [pathname, onPathnameChange]);

  return <p>Child component</p>;
}

When not to use `useEvent`?

Because the hook uses under the hood React reference it should not be called in render, due to problem we could encounter with Concurrent features.
For example a renderItem callback should not be stabilized with useEvent but with useCallback.

Note: In this example it's logic because it's not an event handler.

Note: useEvent should be used when the callback can be prefixed by on or handle.

Question I ask myself

The major question I have is: should it be the component / hook that declares the function that wraps in useEvent or the component / hook that executes the callback?

I am sure that when using a memoized component it should be done at the declaration level, otherwise the memoization won't work:

function MyComponent() {
  const onClick = useEvent(() => {});

  return <MemoizedComponent onClick={onClick} />;
}

In other case, should we do at the declaration like today for useCallback and make a nice documentation telling that it's an event callback?
I think the easiest solution will be at the execution side. Like this we can ensure that the behavior inside the component is the right we want without taking care of how a person uses this one.

The linter part of the RFC, goes in my way:

In the future, it might make sense for the linter to warn if you have handle* or on* functions in the effect dependencies. The solution would be to wrap them into useEvent in the same component.

So it's likely that React pushes to use useEvent at the call site.

Note: The drawback is that it can lead to re-declare new callback each times:

function Button({ onClick: onClickProp, label }) {
  const onClick = useEvent(onClickProp);

  return (
    <button type="button" onClick={onClick}>
      {label}
    </button>
  );
}

In any case, If it's done in both side, double wrap a callback with useEvent should work too :)

Conclusion

I am really waiting for this new hook that will for sure simplify some code. I have already a lot of place in my codebase where it will help a lot.
Do not overused useEffect when you can call some code in event listener just do it ;) Do not change a state, to "watch" it with a useEffect.
Every callback that can be named with the prefix on or handle could be wrapped with this new hook but should we always do it?
Dan Abramov told in a comment that it could be the case, but it's not the aim of the RFC.

In the longer term, it probably makes sense for all event handlers to be declared with useEvent. But there is a wrinkle here with the adoption story with regards to static typing. We don't have a concrete plan yet (out of scope of this RFC) but we'd like to have a way for a component to specify that some prop must not be an event function (because it's called during render).

Maybe the name could change for something like useHandler, because this is not returning an event but an handler.

Once the RFC is validated, the React team should work on recommendation about how to use it.

Are you hyped by this RFC? Do you have any questions?

To be continued :)

Do not hesitate to comment and if you want to see more, you can follow me on Twitch or go to my Website.

Proxy in JS: what the hell?

Romain Trotard — Wed, 20 Apr 2022 19:59:30 +0000

Proxy is something that is commonly used in Java, for example in Spring with Aspect-Oriented Programming (@Transactional, @Security, ....). But in Javascript, it's not something that it is usually used. Or is it? :)

In this article, you are going to see:

the principle
the API
some examples of what we can do
performances
which libraries use it

Principle

The idea is that we are going to create a new object that wraps the original one, and intercepts and redefines fundamental operations such as getting / setting a property, executing a function , ...

More precisely, we are going to proxify a target object (an object, function, ...). And define the operations that we want to intercept / reimplement thanks to an object named handler that contains traps (for example get, set, ...).

Here is an image to resume this:

API

Now it's time to see how to implement Proxy in JS. The API is simple

const proxy = new Proxy(target, handler);

The handler is an object containing all the traps we want to intercept:

const handler = {
  get(target, prop, receiver) {
    console.log("Getting the property", prop);
    return target[prop];
  },
  set(target, prop, value) {
    console.log("Setting the property", prop);
    target[prop] = value;
    return true;
  },
};

Note: You can also use the Reflect API to implement the proxy.

Revocable Proxy

It's also possible to create a Proxy that can be revoked thanks to a given function. Once revoked the proxy becomes unusable.

// `revoke` is the function to revoke the proxy
const { proxy, revoke } = Proxy.revocable(target, handler);

Note: It's not able to restore the Proxy once revoked.

And here we go. You know the API, let's see some example we can implement.

Example of trap

Get

Let's start with the get trap. Its API is:

get(target, property, receiver)

For the example we are going to do a proxy that will throw an error if the user tries to access a property that doesn't exist on the object.

const person = {
  firstName: "Bob",
  lastName: "TheSponge",
};

const personProxy = new Proxy(person, {
  get(target, prop) {
    if (!prop in target) {
      throw new Error(
        `The property ${prop} does not exist in the object`
      );
    }

    return target[prop];
  },
});

// Will print: 'Bob'
console.log(personProxy.firstName);

// Will throw an error
console.log(personProxy.unknownProp);

Apply

The apply trap is the following one:

apply(target, thisArg, argumentsList)

To illustrate it, we are going to implement a withTimerProxy that will measure the duration of a callback execution.

function aFunction(param) {
  console.log("The function has been called with", param);

  return "Hello " + param;
}

function withTimerProxy(callback) {
  return new Proxy(callback, {
    apply(target, thisArg, argumentsList) {
      console.time("Duration");

      const result = callback.apply(thisArg, argumentsList);

      console.timeEnd("Duration");

      return result;
    },
  });
}

const aFunctionWithTimer = withTimerProxy(aFunction);

// Will print:
// The function has been called with World
// Duration: 0.114013671875 ms
// 'Hello World'
console.log(aFunctionWithTimer("World"));

Note: If you want to see more console API you can read my article Unknown console API in JS.

Note: To do such a functionality, we would probably use an High Order Function instead.

Other traps

Here is the exhaustive list of trap you can use:

construct(target, argumentsList, newTarget)
defineProperty(target, property, descriptor)
deleteProperty(target, property)
getOwnPropertyDescriptor(target, prop)
getPrototypeOf(target)
has(target, prop)
isExtensible(target)
ownKeys(target)
preventExtensions(target)
set(target, property, value, receiver)
setPrototypeOf(target, prototype)

Performances?

Recently, I have seen in the react-hook-form implementation, that Bill decided not to use Proxy anymore for the tracking of who watch the state of the form because of performances reasons.

Are the performances so bad? Let's try to measure the performance cost when retrieving the value of a simple property.

I will use the benchmark library. Here is the script I will run:

const Benchmark = require("benchmark");

const suite = new Benchmark.Suite();

const person = {
  firstName: "Bob",
  lastName: "TheSponge",
};

const personProxy = new Proxy(person, {});

suite
  .add("native", () => {
    person.firstName;
  })
  .add("proxy", () => {
    personProxy.firstName;
  })
  .on("cycle", (event) =>
    console.log(event.target.toString())
  )
  .run({ async: true });

The result is the following one:

Of course, the native implementation is faster because it just access the property. The proxy implementation is largely slower than the native one. But I think it's not so bad.

If you search on the internet about, performances of proxy, some people say that it's a tool for development and should not be used in production. Personally, I think it depends on your use case, the amount of data you want to process with Proxy and the performance you want to have. You can test that with a Proof Of Concept (POC).
There are libraries that rely on proxies, which proves that this can be used in production. Let see two of them.

Note: It's good to note that the "selling point" of react-hook-form is the performance, so it makes sense not to use Proxy.

Real use case

SolidJS

SolidJS is a declarative library to build UI, that relies on fine grained reactivity. It does not use a virtual DOM (contrary to React).
The way of writing the code is quite similar to React:

JSX
Component
state => signal
useEffect => createEffect
useMemo => createMemo
...

But there is no hook rules, you should not destructure your props, every components executes ones then it will execute side effect when a used reactive primitive has changed.
It uses Proxy for store which is the equivalent of React reducers.
If you don't know SolidJS, go check it has a promising future.

For example here is a simple Counter component:

import { createSignal } from 'solid-js';

function Counter() {
  const [count, setCount] = createSignal(0);
  const increment = () => setCount(count() + 1);

  return (
    <button type="button" onClick={increment}>
      {count()}
    </button>
  );
}

Note: This is not an exhaustive list of similarities / differences and how to use the library. When I feel more confident, I will try to write an article about it because I think it has a bright future ahead of it.

ImmerJS

ImmerJS allows us to create immutable data structures, but giving us the possibility to change its data in a mutable way.

For example, you will able to do:

import product from "immer";

const person = {
  firstName: "Bob",
  lastName: "TheSponge",
};

const newPerson = produce(person, (p) => {
  p.firstName = "Patrick";
  p.lastName = "Star";
});

// Will return false
console.log(newPerson === person);

It's a convenient way to simplify changes without mutates an object, and without to make a lot of copy.

const person = {
  firstName: "Bob",
  lastName: "TheSponge",
  address: {
    type: "pineapple",
    city: "Bikini bottom",
  },
};

// It prevents us to make things like
const newPerson = {
  ...person,
  address: {
    ...person.address,
    // Note the uppercase
    type: "Pineapple",
  },
};

Note: Redux Toolkit uses it under the hood to make reducers easier to implement.

Conclusion

Proxy enables a lot of features, thanks to them you can extract some logic that will be reusable. Some libraries use them to optimize your code execution. For example react-tracked and proxy-memoize that use, proxy-compare under the hood, will reduce your re-render. These libraries are developed by Dai Shi who also made the use-context-selector library that I demystified in the article use-context-selector demystified.
But I would recommend you to use them uniquely when it's necessary.

There is a TC39 proposal to add natively Decorators to javascript, looks promising, which will enable some other possibilities. For example to log / measure performance of function, ... in an easy way: with a @Logger or @Performance (with the right implementation behind these annotations).

Do not hesitate to comment and if you want to see more, you can follow me on Twitter or go to my Website.

useImperativeHandle: the most unknown React hook

Romain Trotard — Wed, 06 Apr 2022 16:27:53 +0000

Among all the native React hooks that exist, there are well known ones like useState, useEffect and less known ones like useImperativeHandle.

This last hook is the subject of this article that I teased in my last article about React references.

At the end of this post, you will know what problem is solved with it, how to use it and a real use case where it's needed to be more concrete.

Buckle up, let's go.

Introduction

In React, like in some other libraries, the data flow is unidirectional going top-down in the component tree. It means that a parent component can configure a child component thanks to properties.
So in a sense, a child can have access to an element of the parent when passed as property. But a parent can't have access to an element of the child, or so you think.

Note: We can inverse the data flow, by passing callback and value, for example when controlling components :)

If you want to expose a callback from the Child it can expose a register to register this callback:

function Child({ register }) {
  useEffect(() => {
    const aFunction = () =>
      console.log("A function inside the FC");
    register(aFunction);
  }, [register]);

  return <p>Child</p>;
}

function Parent() {
  const childCallback = useRef();

  const register = useCallback((callback) => {
    // I use a ref but could be a state 
    // if needed to display JSX
    childCallback.current = callback;
  }, []);

  return <Child register={register} />;
}

Well, it works but it adds some boilerplate which is not the easiest to understand how it works.
It's time to go deep in the subject.

Warning: You should not have to expose a state or variable from a child, in this case you would have to change the API and put the state up.

Note: If you want to know more about React state, you can read my article Things you need to know about React state.

Some context with Class components

Firstly, I would like to talk about the behavior of ref with Class component.

Note: If you want to know more about ref you can see my article Things you need to know about React ref.

When we pass a ref to a Class component then we get the React element instance.

class ClassComponent extends React.Component {
  aFunction = () => console.log("A function inside the CC");

  render() {
    return <p>A class component</p>;
  }
}

function Parent() {
  const myRef = useRef();

  useEffect(() => {
    // Will log the React element instance
    console.log(myRef.current);
  }, []);

  return <ClassComponent ref={myRef} />;
}

It will then log:

Thanks to that, you can call imperatively any method of a Class component child from its parent thanks to the ref.

function Parent() {
  const myRef = useRef();

  return (
    <>
      <ClassComponent ref={myRef} />
      <button
        type="button"
        onClick={() => myRef.current.aFunction()}
      >
        Executes aFunction
      </button>
    </>
  );
}

Note: Even if you have access to the render method, do not call it!

Work with Functional components

If you try to do the same with a Functional child component, you will get the log undefined.

function FunctionalComponent() {
  const aFunction = () =>
    console.log("A function inside the FC");

  return <p>A functional component</p>;
}

const ForwardedRefFunctionalComponent = React.forwardRef(
  FunctionalComponent
);

function Parent() {
  const myRef = useRef();

  useEffect(() => {
    // It will log `undefined`
    console.log(myRef.current);
  }, []);

  return <ForwardedRefFunctionalComponent ref={myRef} />;
}

Note: We need to forwardRef with Functional component when customizing the reference named ref. But you can pass a reference as an usual prop and customize it too without the need of forwardRef.

function FunctionalComponent({ aRef }) {
  const aFunction = () =>
    console.log("A function inside the FC");

  return <p>A functional component</p>;
}

function Parent() {
  const myRef = useRef();

  return <ForwardedRefFunctionalComponent aRef={myRef} />;
}

You probably have guessed it, useImperativeHandle will help you to solve it. The hook allows to expose some method of a child FC to its parent by customizing the passed reference.

How to use it?

Now that we have the purpose of this hook, let's see how to use it.

It takes 3 parameters:

the reference to customize
the APIs to expose as a callback
an optional array of dependencies (when handler depends on state): has the same behavior than useEffect array dependency

Note: Like useEffect, if you do not pass an array (as third argument), the API callback will be executed at each render.

useImperativeHandle(ref, createHandle, [deps])

For example with the the previous example it will be:

function FunctionalComponent(props, ref) {
  useImperativeHandle(ref, () => ({
    aFunction: () =>
      console.log("A function inside the FC"),
  }));

  return <p>A functional component</p>;
}

And now the log will be:

Amazing, right? :)

Note: You can also attach the ref to a DOM node (not possible with Class component) ;)

A use case example

Well, now that you know how to use the hook, it's time to see a real use case where the component API is good and it's useful to use useImperativeHandle.

When displaying a list with a lot of elements, for example like Twitter, you can encounter some layout performances issues. This is where virtualization comes in handy.
Basically, only the elements displayed on the screen are present in the DOM (with few element before and after) which makes the DOM much lighter.

To do that you would make a component named VirtualizedList which will handle virtualization. Behind the hood, there are some calculations in function of the height of rows and handling position to know which rows need to be in the DOM and where they are displayed on the screen.

We would like to be able to scroll to a specific items, in an imperative way. It's the perfect use case for useImperativeHandle:

function VirtualizedList(props, ref) {
  useImperativeHandle(ref, () => ({
    scrollTo: (itemId) => {
      // Do some process
    },
  }));

  return (
    <ul>
      {
        // Right items to display
      }
    </ul>
  );
}

Conclusion

Alright, now you have seen you can expose an API from a child to its parent, but do not overused it. Most of the time you will think you need it, it's probably that the API of your component is not right.
It's possible to do it in Class components and in Functional components as well. In FC, do not forget to forwardRef otherwise it would not work.

Do not hesitate to comment and if you want to see more, you can follow me on Twitter or go to my Website.

Forem: Romain Trotard

Serverless function cold start is too slow, let's dockerize our app

Dockerfile

Deployment workflow

Get the previous version and increment it

Build and push docker image

Create and push git tag

Deploy the docker image on my server

Conclusion

React routing library with Navigation API

useSyncExternalStore

React implementation

Getting loader data

navigate an prompt before leave features

useNavigate

usePrompt

Conclusion

Master the Art of Navigation: Building a Library with the Navigation API

Specifications

How to keep things agnostic?

Backbone code

Single Page Application

Navigation inside the app

Routes implementation

loaderData feature

Prompt before leave feature

Conclusion

Back to the future: Navigation API

New NavigationHistoryEntry

Entry list

Current entry

New way to to navigate between pages

committed and finished returned values

Loading feedback

Navigation through the entry list

Reload of the page

Go to the previous page

Go to the next page

Go to a more distant entry

New NavigationEvent

Blocking navigation

Simulating SPA

Conclusion

React Hook Form: a unique implementation

Prerequisites

What would be a "simple" implementation?

Key points of React Hook Form implementation

Do not use React state

Observer pattern

Proxies / defineProperty

Stable event listener with no stale external data

Conclusion

Track your test duration

Overview of My Submission

Submission Category

Language Used

Link to Code

romain-trotard / redis-timing-tracker

Redis Timing Tracker

What is it?

How it works

Stack used

Pub/sub messages

Additional Resources / Info

Javascript CLI demystified

Initialization of the library

Let's make some code

Let's make the CLI stuff

How does it work?

Add a package globally on your machine

How does global package work?

Conclusion

Exit animation with `framer-motion` demystified

Exit animation with framer-motion

Under the hood

Make enter and exit animation

Get all valid children

Keep children of previous render

Get key of children and determine removed keys

Get removed elements

`loaderData` feature

`committed` and `finished` returned values

Exit animation with `framer-motion`

Injection of `isVisible` into `AnimatedComponent`

`useForceRender` hook

When not to use `useEvent`?