DEV Community: Francois Zaninotto

New client-side hooks coming to React 19

Francois Zaninotto — Tue, 23 Jan 2024 12:04:11 +0000

Contrary to popular belief, the React core team isn't solely focused on React Server Components and Next.js. New client-side hooks are coming in the next major version of React, React 19. They focus on two major pain points in React: data fetching and forms. These hooks will enhance the productivity of all React developers, including those working on Single-Page Apps.

Without further ado, let's dive into the new hooks!

use(Promise)
use(Context)
Form actions
useFormState
useFormStatus
useOptimistic
Bonus: Async transitions

Note: These hooks are only available in React’s Canary and experimental channels. They should be part of the upcoming React 19, but the API may change before the final release.

use(Promise)

This new hook is the official API for "suspending" on the client. You can pass it a promise, and React will suspend on it until it resolves. The basic syntax, taken from the React use documentation, is:

import { use } from 'react';

function MessageComponent({ messagePromise }) {
    const message = use(messagePromise);
    // ...
}

The great news is that this hook can be used for data fetching. Here is a concrete example with data fetching on mount and on click on a button. The code doesn't use a single useEffect:

Remember this warning in the <Suspense> documentation?

Suspense-enabled data fetching without the use of an opinionated framework is not yet supported.

Well, it's no longer true for React 19.

This new use hook has a hidden power: Unlike all other React Hooks, use can be called within loops and conditional statements like if.

Does that mean that we no longer need to use a third-party library like TanStack Query to fetch data on the client side? Well, it remains to be seen, as Tanstack Query does more than just resolving a Promise.

But it's a great step in the right direction, and it will make it easier to build Single-page apps based on REST or GraphQL APIs. I'm super enthusiastic about this new hook!

Read more about the use(Promise) hook in the React documentation.

use(Context)

The same use hook can be used to read a React Context. It's exactly like useContext, except it can be called within loops and conditional statements like if.

import { use } from 'react';

function HorizontalRule({ show }) {
    if (show) {
        const theme = use(ThemeContext);
        return <hr className={theme} />;
    }
    return false;
}

This will simplify the component hierarchy for some use cases, as the only way to read a context in a loop or a conditional was to split the component in two.

It's also a great evolution in terms of performance, as you can now conditionally skip the re-rendering of a component, even though the context has changed.

Read more about the use(Context) hook in the React documentation.

Form Actions

This new feature enables you to pass a function to the action prop of a <form>. React will call this function when the form is submitted:

<form action={handleSubmit} />

Remember that if you add a <form action> prop in React 18, you get this warning:

Warning: Invalid value for prop action on <form> tag. Either remove it from the element or pass a string or number value to keep it in the DOM.

That's no longer true in React 19, where you can write a form like this:

The addToCart function is not a Server Action. It is called on the client side, and it can be an async function.

This will greatly simplify the handling of AJAX forms in React - like for instance for a search form. But again, this may not be enough to get rid of third-party libraries like React Hook Form, which does much more than just handle form submission (validation, side effects, etc).

Tip: You may find some usability issues in the example above (submit button not disabled while submitting, missing confirmation message, late update of the cart). Fortunately, more hooks are coming to help with this use case. Read on!

You can read more about the <form action> prop in the React documentation.

useFormState

This new hook aims to help with the async form action feature described above. Call useFormState to access the return value of an action from the last time a form was submitted.

import { useFormState } from 'react-dom';
import { action } from './action';

function MyComponent() {
    const [state, formAction] = useFormState(action, null);
    // ...
    return <form action={formAction}>{/* ... */}</form>;
}

For instance, this lets you display a confirmation or an error message returned by the form action:

Note: useFormState must be imported from react-dom, not react.

You can read more about the useFormState hook in the React documentation.

useFormStatus

useFormStatus lets you know if a parent <form> is currently submitting or has submitted successfully. It can be called from children of the form, and it returns an object with the following properties:

const { pending, data, method, action } = useFormStatus();

You can use the data property to display what data is being submitted by the user. You can also display a pending state, as in the following example where the button is disabled while the form is submitting:

Note: useFormState must be imported from react-dom, not react. Also, it only works when the parent form uses the action prop described above.

Together with useFormState, this hook will improve the user experience of client-side forms without cluttering your components with useless context of effects. You can read more about the useFormStatus hook in the React documentation.

useOptimistic

This new hook lets you optimistically update the user interface while an action is being submitted.

import { useOptimistic } from 'react';

function AppContainer() {
    const [optimisticState, addOptimistic] = useOptimistic(
        state,
        // updateFn
        (currentState, optimisticValue) => {
            // merge and return new state
            // with optimistic value
        },
    );
}

In the cart example above, we could use this hook to display the cart with the new item added before the AJAX call is finished:

Optimistically updating the UI is a great way to improve the user experience of a web app. This hooks helps a lot with this use case. You can read more about the useOptimistic hook in the React documentation.

Bonus: Async Transitions

React's Transition API lets you update the state without blocking the UI. For instance, it lets you cancel a previous state change if the user changes their mind.

The idea is to wrap a state change with a call to startTransition.

function TabContainer() {
    const [isPending, startTransition] = useTransition();
    const [tab, setTab] = useState('about');

    function selectTab(nextTab) {
        // instead of setTab(nextTab), put the state change in a transition
        startTransition(() => {
            setTab(nextTab);
        });
    }
    // ...
}

The following example shows a tab navigation using this Transitions API. Click “Posts” and then immediately click “Contact”. Notice that this interrupts the slow render of “Posts”. The “Contact” tab shows immediately. Because this state update is marked as a transition, a slow re-render did not freeze the user interface.

The useTransition hook is already available in React 18.2. What's new in React 19 is that you can now pass an async function to startTransition, which is awaited by React to start the transition.

This is useful for submitting data through an AJAX call and rendering the result in a transition. The transition pending state starts with the async data submission. It is already used in the form actions feature described above. This means that React calls the <form action> handler wrapped in startTransition, so it doesn’t block the current page.

This feature isn't yet documented in the React documentation, but you can read more about it in the pull request.

Conclusion

All of these features work in client-only React apps, for instance in apps bundled with Vite. You don't need an SSR framework like Next or Remix to use them - although they also work with server-integrated React apps.

With these features, data fetching and forms become significantly easier to implement in React. However, creating a great user experience involves integrating all these hooks, which can be complex. Alternatively, you can use a framework like react-admin where user-friendly forms with optimistic updates are built-in.

Why are these features coming to React 19 instead of React 18.3? It seems that there will not be a 18.3 release because these features include some minor breaking changes.

When is React 19 coming? There is no ETA yet, but all the features mentioned in this post are already working. I wouldn't recommend using them yet, though - using a canary release in production is not a good idea (even if Next.js does it).

It's really nice to see that the React core team is working on improving the developer experience of all React developers, not only those working on SSR apps. It also seems they're listening to the community feedback - data fetching and form handling are very common pain points.

I'm looking forward to seeing these features in a stable release of React!

Documentation: The Key Enabler For Open-Source Success

Francois Zaninotto — Wed, 10 Jan 2024 13:51:33 +0000

In the Open Core business model, customers aren't acquired through marketing. Rather, the open-source core library gains users organically, who are then converted into customers. A key factor in this conversion process is documentation.

When we first introduced the documentation for react-admin, our open-source framework for developing admins & B2B applications, we received an overwhelmingly positive response. As react-admin has grown into a larger framework with both free and commercial features, maintaining the same level of user satisfaction has become a challenge. Through this journey, we've gained significant insights about documentation, which we aim to share in this article.

React-admin Docs In A Nutshell

First, let's look at the current state of the react-admin documentation. At the time of writing, it consists of:

255 web pages with a total of 55,000 lines of content (text+code)
485 pictures & videos
times 12 because we also have documentation for previous versions

That's, by today's standards, a lot of documentation.

The documentation website is visited by around 40,000 visitors per month (according to our privacy-friendly analytics tool, Umami).

But in fact, we publish many more learning materials than the documentation website. We also have:

Two storybooks (one for the open-source edition, and one for the Enterprise ) totaling about 420 story files and 2,300 individual stories
89 blog posts & tutorials
5 real-life demos with source code
Error messages
Issues & code reviews on GitHub
In-IDE documentation
- TypeScript types
- JSDoc

Why Documentation Matters

We need documentation, but often for different (and sometimes conflicting) reasons.

Library users want to:

Understand if the project is a good fit for their use case (accessible, rich features)
Learn the basics to get started
Find the right hook/component for their use case
Understand what a feature does and if it applies to them
Find the right syntax for a hook/component
Troubleshoot errors
Discover new features
Learn best practices

Library authors write documentation to:

Encourage contributions
Minimize support costs
Showcase paid features and recruit customers

It's challenging to cater to all these diverse needs, and there's a good chance of messing up.

Doc Pitfalls To Avoid

I read a lot of tech documentation, and I often struggle to find basic answers or grasp the big picture. Is this a problem with the documentation, or with me? I'm not sure.

I don't read documentation like a book, from start to finish. I search for specific solutions to my problems. My entry point is usually a search engine.
I avoid long pages. I quickly look at the headings and pictures. If I can't find what I need in a minute or two, I look somewhere else.
When I look at a page of documentation, I skip paragraphs of text to focus on code examples. If the code isn't self-explanatory, I'll read the text, but I'll likely skim it.
If I can't copy/paste the code examples I found in the documentation and run them without error, I lose confidence in the library.
I find that examples using "foobar" and "lorem ipsum" are not helpful. I don't like to make the effort of converting the example domain into something I can relate to. I prefer real-life examples that I can understand effortlessly.
I need to feel a clear path of progression: knowing what to learn next.
I look for different things when I'm a beginner than when I'm an experienced user. As a beginner, advanced features are overwhelming. But as an experienced user, I want to know about them.
I seldom read the "What's new" section or compare the index of the documentation with the previous version. Yet I want to know about new features.

In the process of writing the react-admin documentation, we've tried to address these concerns and design the documentation for people like us.

13 Tips For Writing Great Documentation

We learned to balance technical details with readability. Here are some of the techniques we use:

Guide-first: The first contact with the documentation is through guides, which illustrate a feature in a simple example. Guides are non-exhaustive, beginner-friendly, and focus on the most common use cases. Reading only the guides should be enough to get started. A good example of a guide is of course the Getting Started tutorial page. The doc for each react-admin component starts with a "Usage" section that is also a guide (for instance, the <List> component Usage).
Show, don't tell: We include as many screenshots and screencasts as possible, and early in the doc. For instance, the documentation for the <Datagrid> component starts with a screencast of the component being used. Making images and videos is super time-consuming, but it's worth it.
More code than text: A good example is worth a thousand words, and that's even more true for developers. We limit the amount of text in the documentation, and we try to show as much code as possible. For instance, the documentation for the <List> component has 1,000 non-empty lines, 70% of which are code.
Examples use plausible data: We avoid as much as possible dummy text in our examples. Instead, we carefully craft real-looking data (for instance in the HelpDesk demo). Readers need less effort to transpose such examples to their use case, and it's also more appealing. We use Faker.js to generate fake data - but to make it plausible, we spend an enormous amount of time tweaking it.
Examples are also Stories: To make sure the code examples are bug-free, and to have screenshots that match the code examples, we start by writing stories in Storybook. Then we use the stories as a base for the documentation. For instance, the story for the <InfiniteList> component serves as a base for the documentation for the <InfiniteList> component.
The reference follows the guide: If an advanced user looks for all possible options of a component, they can find them in the same place as the guide. For instance, the list of props for the <List> component is just below the "Usage" section. This is a different approach from e.g. the Material UI documentation, where the reference is on a separate page.
Pages can be quickly scanned: Documentation pages consist of various short sections of text, code, titles, callouts, and so on. No section should be longer than half a page, allowing readers to swiftly locate the information they need.
A feature has several names: We use several words to describe a given feature so that the page can be found by searching any of these words. For instance, the <LocalesMenuButton> component is also described as a "language switcher", so that it can be found by searching either "language" or "switcher".
Features are documented several times: In each guide, we document a few HowTos for common use cases. HowTos often use other components, and it's a good way for users to discover these components by chance (a.k.a. "serendipity"). For instance, the <Edit> documentation has a section called "Navigation through records" that explains how to use the <PrevNextButtons> components. This component also has its own page, and the basic usage is copied on both pages.
Overview sections: For every feature group, we provide an overview section that outlines the concepts, terminology, and functionalities. This gives beginners a broad understanding before they delve into specifics. For instance, there are more than 30 chapters about the Input components. In the Inputs Overview, we clarify what an Input is, the common props, how to select the right input, and so on.
Beginner mode: The react-admin documentation consists of 255 individual chapters, but beginners can turn on the "Beginner mode" to hide the advanced chapters and reduce the navigation to 77 chapters. This is a good way to avoid overwhelming beginners with advanced features.
Eat your own dog food: We rotate the core team so that each developer can work regularly on projects based on react-admin. As we can't keep all the documentation in our heads, we have to use the documentation website constantly. So we're in the shoes of our users, which lets us detect usability issues.
Mixed open-source and commercial features: The documentation for the Enterprise Edition is mixed with the documentation for the open-source edition. Enterprise Edition features are marked with an "Enterprise" badge. This is a good way to showcase the paid features and recruit customers where they are most likely to be found.

As a consequence, the structure of most pages is:

1-sentence summary
screenshot or screencast
usage example
list of parameters
usage example and detailed instructions for each parameter
advanced usage examples and how-tos
related components

This is reflected in the documentation for the <SimpleShowLayout> component:

Write Once, Maintain Forever

One key lesson we learned is that documentation is never finished. It's a living thing that needs to be maintained and updated regularly.

The react-admin documentation is written in Markdown, and published to HTML using Jekyll. It lives in the same repository as the code (marmelab/react-admin), and is versioned with the code.

Every pull request adding or modifying a feature must also update the documentation.

If a user raises an issue (or a support request) about something they didn't understand, we update the documentation to make it clearer. A good answer to a support request is a link to the documentation.

We also review the documentation regularly to make sure it's up to date. That means re-reading an entire section of the documentation from start to finish.

This explains why, in the changelog of any react-admin release, you'll find about 50% of the entries are about documentation.

Writing and maintaining the react-admin documentation up to date costs us about one full-time developer.

Going Further

Despite the efforts we've put into the documentation, we still have a lot of room for improvement. Here are the areas we've identified as needing improvement:

The navigation sidebar needs foldable sections. The current sidebar is too long, and it's hard to find the right section.
Dark Mode. Many readers have dark mode turned on in their OS, and they expect the documentation to follow suit.
Executable code examples. We've refrained from using CodeSandbox for examples because its iframes are slow and heavy. However, we need to find a way to let users test the code examples without leaving the documentation.
Be more concise. We need to further reduce the amount of text in the documentation, and focus on code examples.
Better IntelliSense. We need to improve the JSDoc and TypeScript types so that the IDE can provide better IntelliSense.

Conclusion

We've seen firsthand how powerful good documentation can be. It turns users into contributors, projects into communities, and open-source into a business.

Maintaining a large corpus of documentation to a high level of quality is super expensive. But it pays off: we see a constant flow of new users who discover, test, and learn the framework by themselves. They contribute, too: react-admin has more than 570 contributors, most of whom we've never met. We get relatively few support requests (about a dozen per day). Overall, the quality and coverage of the documentation let us handle the support of our current customer base with about half a full-time developer. Finally, users convert naturally into customers at a constant rate of about 20 new customers per month.

From our point of view, we've reoriented the budget that other teams put into marketing and sales into documentation. Documentation is an investment that pays off in the long run.

In the end, we also spend a lot of time writing documentation because we like it. Writing documentation regularly makes us better developers, as we detect and fix usability issues in the library.

Anatomy Of A Profitable Open-Source Project

Francois Zaninotto — Tue, 14 Nov 2023 10:11:25 +0000

It’s challenging to find public business metrics about digital products. Most companies keep these secret for fear that competitors might replicate their strategies.

We’ve developed a business based on an open-source platform called react-admin. Embracing the open-source spirit, we’re sharing the key performance indicators of this business. We hope it will help other open-source developers build their own business.

This article is the second in a series about transforming React-Admin into a profitable open-source project with nearly €1M in revenue. Read the other articles in this series:

Turning Open-Source Into Profit: Our Journey.
Anatomy Of A Profitable Open-Source Project (this article).

Usage and Popularity

React-admin was launched in 2016 as a frontend framework for building data-driven applications atop of REST/GraphQL APIs. It was created to leverage the code we developed for our clients. We have continually updated the code, incorporating new features and documentation since its inception.

React-admin has quickly gathered a lot of interest in the open-source community. Today, it has more than 23,000 stars on GitHub.

That’s 23,000 real developers who bookmarked this project. But how many actively use it?

Applications built with React-Admin are accessed almost 500,000 times every weekday. Every minute, roughly 350 people initiate a new session on an application developed using React-Admin. These people come from all over the world.

We gather these metrics using a custom, anonymous telemetry tag in React-Admin, which users can choose to disable.

In July 2020, we launched an Enterprise Edition of react-admin. While only a small portion of our user base subscribes to this edition, the number of active subscribers is steadily increasing.

Key Performance Indicators

The core of react-admin is free and open-source. The paid version, react-admin Enterprise Edition, contains additional modules and support. This follows the OpenCore business model, popularized by renowned libraries like Kafka, GitLab, and Elastic.

React-Admin Enterprise Edition is subscription-based, starting at €135/month. Customers pay for the duration of their project development. Once development concludes, they may discontinue the subscription and still use the code for free. On average, customers subscribe for 9 months.

Subscription durations vary significantly. There are two customer cohorts: those who subscribe for a few months and those who subscribe for several years. About one-third of our customers choose a yearly plan (which is 10% cheaper), while the rest opt for monthly plans.

Our monthly customer loss rate, or "churn," is high due to our billing model, which aligns with project development duration. The churn rate stands at 7%.

Subscription pricing is team-size dependent:

90% of our customers are on the “Team” plan. We operate on a trust basis regarding team size; we verify only that those contacting our support are part of the subscription.

Since 2020, we've had over 600 paying customers.

The Enterprise Edition includes 16 private modules, offering features like authorization, live updates, and navigation. The most popular modules are:

Form Layout (alternative layouts for Edition and Creation pages)
Navigation (breadcrumb, menus, and alternative app layouts)
Relationships (specialized components for displaying and editing records in a many-to-many relationship)
Markdown (render and edit Markdown content)
Editable Datagrid (spreadsheets-like edition of records)

Download numbers are interpreted cautiously, as large teams with active CI can skew the totals.

The Enterprise Edition also gives access to support by email. We handle about a dozen support requests daily, mostly complex issues as easier ones are resolved using our documentation. This equates to approximately 4 hours of support work daily.

Revenue And Costs

React-Admin's revenue is solely from customer subscriptions. We don’t utilize ads, donations, training, certifications, or sponsorships. Although React-Admin generates significant business opportunities for our web agency, these are not included in the React-Admin revenue.

The average revenue per user (ARPU) is 1,400€. This figure is skewed by a few large, long-term customers, even though most subscribe to the cheapest plan for only a few months.

The average monthly revenue over the past year is €35k, projecting about €420k in revenue this year for React-Admin Enterprise Edition.

Revenues have increased 35% year over year. Since inception, react-admin has generated approximately €1 Million in subscription revenue. Indirect revenue, including business for our web agency, is significantly higher.

Cost-wise, we dedicate 4 full-time employees to this product: 3 developers, and combined roles of half Sales and half Marketing assistant.

Our technical costs are minimal, around €2k annually (for hosting an npm registry and a customer dashboard). Blog content creation is part of the development team’s responsibilities, so it's included in the cost of the 4 full-time employees.

Sales tool expenses are modest. We use LinkedIn for lead generation and a cost-effective CRM (Highrise) for tracking. Communication is through email, WhatsApp, and chat (powered by Chatwoot).Our marketing budget is around €20k this year, primarily for tech newsletter sponsorships.

In total, the development, support, updates, prospecting, and operations amount to approximately 350k€ annually. This confirms that react-admin is profitable.

As for the Average Rate of Return (ARR), we don't calculate it; React-Admin is not viewed as an investment. All profits are reinvested into the product.

Conclusion

The revenue from the Enterprise Edition covers the full-time salaries of our four-person team and also funds the development of the open-source version of React-Admin.

An annual revenue of €400k may seem modest compared to larger SaaS and enterprise software companies. Indeed, there is potential for much greater earnings, and if you're involved in SaaS product development, you're probably not impressed.

But this business line is profitable, and a great bonus to our core business (web development). We have no debt, and we're free to do whatever we want.We operate debt-free, with the autonomy to make our own decisions. There's no pressure to satisfy investors or pursue aggressive growth. In essence, we are happy with what we have. We consider ourselves extremely lucky to earn a living through open-source work, and we are immensely thankful to our customers for making this possible.

How did we get there? Read the next article in this series to find out.

React Without useEffect

Francois Zaninotto — Thu, 13 Apr 2023 05:38:47 +0000

useEffect is the hardest part of React - and the most error-prone. Getting a complete understanding of useEffect takes a 49 minutes read. I've already explained my concerns about useEffect in another article: In my opinion, useEffect is the biggest pain point of React.

But what if we could build entire React apps without useEffect?

A Complete React App Without `useEffect`

Check out this Help Desk application. It's a fully-functional React app that does all the things you'd expect, from ticket search to multi-agent collaboration.

It does data fetching, syncs the list filters with the URL, stores user preferences in localStorage, shows real-time notifications, manages content locks, updates data when another user does a mutation, and more. All without useEffect (check the source). And this is true React - not Solid.js or Svelte. So how does it work?

Of course, there is a trick: this application uses a React framework - in that case, react-admin. The primary function of React frameworks is to make React easier to use for specific use cases. For React-admin, it's for admin and B2B single-page apps.

My point is: if you want to build a React app, you should use a framework. Let's see why.

Declarative Data Fetching

Take the customer column on the messages list. It has to fetch the customer name for each ticket. How would you write it in pure React?

Here is a basic React implementation:

const CustomerNameField = ({ record }) => {
    const [customer, setCustomer] = useState(null);
    const [loading, setLoading] = useState(true);
    const [error, setError] = useState(null);
    useEffect(() => {
        setLoading(true);
        fetch(`${API_URL}/customers/${record.customer_id}`)
            .then(response => {
                setCustomer(response.data);
                setLoading(false);
            })
            .catch(error => {
                setError(error);
                setLoading(false);
            });
    }, [record.customer_id, setCustomer, setLoading, setError]);
    if (loading) {
        return <Loading />;
    }
    if (error) {
        return <Error />;
    }
    if (!customer) {
        return null;
    }
    return <span>{customer.name}</span>;
};

If you look at the code of the HelpDesk app, you will see that the actual CustomerNameField component is actually much simpler:

const CustomerNameField = () => (
    <ReferenceField reference="customers" source="customer_id" />
);

This JSX code says "display the related customer whose id is in the customer_id field". It's a declarative syntax, which means that you ask the program what you want to display, and not how to fetch and render the data.

Under the hood, react-admin's <ReferenceField> component does use useEffect for data fetching, but that's an implementation detail that you don't need to worry about.

And <ReferenceField> actually does way more than the initial code. When used in a data table, it aggregates and deduplicates the calls for all the customers in the table. It then sends a single request to the API, with a WHERE IN clause.

Declarative Data Sync

Now, take the lock system. When another user locks a ticket, the current user sees the ticket as locked, and cannot post a reply.

To implement that in pure react, the <TicketActivity> component has to fetch the lock on mount, subscribe to the lock changes, update the lock state when the lock changes, and unsubscribe when the component is unmounted:

const TicketActivity = ({ record }) => {
    const [lock, setLock] = useState(null);

    useEffect(() => {
        setLoading(true);
        fetch(`${API_URL}/locks/tickets/${record.id}`).then(response => {
            setLock(response.data);
        });
    }, [record.id, setLock, setLoading, setError]);

    useEffect(() => {
        const subscription = subscribeTo(
            `locks/tickets/${record.id}`,
            event => {
                if (event.data.type === 'locked') {
                    setLock(event.data.payload);
                }
                if (event.data.type === 'unlocked') {
                    setLock();
                }
            },
        );
        return () => subscription.unsubscribe();
    }, [record.id, setLock]);

    if (!lock) return null;
    return (
        <Typography variant="body2">
            Locked by
            <ReferenceField
                record={lock}
                source="identity"
                reference="agents"
            />
        </Typography>
    );
};

That's two useEffect calls, and a lot of code - I've even left out the loading/error states. Now look at the <TicketActivity> implementation in the HelpDesk app. It looks like this:

const TicketActivity = () => {
    const { data: lock } = useGetLockLive('tickets');
    if (!lock) return null;
    return (
        <Typography variant="body2">
            Locked by
            <ReferenceField
                record={lock}
                source="identity"
                reference="agents"
            />
        </Typography>
    );
};

The useGetLockLive hook says: "I want to get the lock for the current ticket, and I want it to be refreshed in real-time when the lock changes in the backend". Again, it's declarative: how this is done is not important, or rather, it's left to react-admin.

This time, react-admin replaces calls to useEffect not by a component, but by another custom hook. Yet this hook has no dependency array, and the developer doesn't have to worry about rerenders, cleanup on unmount, and all that plumbing. The custom hook hides the complexity behind a task-oriented API.

The Help Desk app contains tons of components that would normally require many useEffect calls, but that use higher-level, business-oriented APIs. One exception: the useAddReadToTicket hook uses useAsyncEffect to create a new record on mount. This hook is a useEffect wrapper that allows asynchronous code (and is explained in a previous post). But that's it.

But That Doesn't Work In My Case

You may say: "That declarative syntax works for simple cases, but I often have to use useEffect and I see no way around it". Well, we've built many React apps (including an e-commerce admin and a CRM) that don't call useEffect even once. So yes, it's possible.

There is a price to pay, of course: You have to learn The Framework Way™ to handle relationships, search & filtering, roles & permissions, Pub/Sub, user preferences, etc. instead of doing it your way. Before becoming more efficient, you'll have to develop at a slower pace.

And sometimes, the framework gets in the way and doesn't let you do exactly what you want. In those cases, you'll fall back to pure React, and you'll probably have to use useEffect directly. I do too, sometimes, and the pain it brings makes me wish react-admin had a declarative API for that use case. Using a framework greatly reduces the amount of imperative code you have to write, but it doesn't eliminate it.

Conclusion

React is supposed to favor declarative code over imperative code. But since its API is tiny, many features require imperative boilerplate, with the help of useEffect. It's as if React were missing a layer to really let developers write declarative code in most use cases.

Libraries and frameworks fill that gap. React-query, react-hook-form, react-router, MUI, and emotion use useEffect so that you don't have to. React-admin builds up on these libraries, and exposes higher-level components and hooks to let you build complex, declarative React apps free of useEffect.

Like a CRUD app in 13 lines of code:

import React from 'react';
import { Admin, Resource, ListGuesser } from 'react-admin';
import simpleRestProvider from 'ra-data-simple-rest';

const dataProvider = simpleRestProvider('https://domain.tld/api');

const App = () => (
    <Admin dataProvider={dataProvider}>
        <Resource name="users" list={ListGuesser} />
    </Admin>
);

export default App;

Whether you are a new React developer or a seasoned one, useEffect is probably your biggest productivity killer. Don't let it get in the way of your creativity. Use a React framework. And if you don't know which one to choose, give react-admin a try.

Using Copilot to Review Code And Fund Open-Source Projects

Francois Zaninotto — Wed, 29 Mar 2023 07:54:48 +0000

What if we could use AI to spot bugs, suggest improvements, and make code reviews more efficient? And what if this provided a way to pay open-source maintainers for their work?

Copilot Only Gets You So Far

Copilot is a game changer - it helps me write code faster, focus on the complicated (and interesting) part of software development, and it's addictive. It made me an augmented programmer.

But Copilot is designed to write code based on existing codebases. It also relies on Codex, a stripped-down GPT-3 model designed to be faster than the original model. It also doesn't know the context of the code it's writing, so it can't always suggest the right thing.

As a result, we still need code reviews. First and foremost, the developer who uses Copilot must write unit tests, and more generally make sure the code is correct. This kind of reverses the role of the developer: our primary goal isn't to write code anymore, but to review it.

Peer Code Reviews Are A Blessing

There is another type of review that is immensely valuable: peer code reviews. When a fellow developer takes a look at a pull request with fresh eyes, they see problems that the original developer missed. They see the final result of the feature development, not the process, and they see it as a "diff", which makes it easier to spot problems.

I am very fortunate to have killer peer reviewers in my team (among many others, @slax57 and @djhi), who regularly find tricky bugs in my code before it gets merged. Check this pull request for instance:

This is so valuable that in my company, Marmelab, peer review is a requirement - developers cannot merge their own PRs, they need a fellow developer to review their code first.

Because of the advent of Copilot, every PR now has 2 reviewers: the original developer, and the peer reviews. That's great! But we can do better.

Using GPT3 to Review Code

What if GitHub had an AI code reviewer baked in? I tried to ask ChatGPT to review the same PR as mentioned above, and the results were... encouraging.

The prompt was super basic:

Now imagine if I could interact not with a generic GTP-3 model, but with a model trained not only with code but with the best code reviews in its dataset. The model size wouldn't be such a problem as code review usually takes hours, so we can wait minutes. And the model could be specifically trained on the project codebase for more relevant suggestions.

The result would be a superhuman code reviewer, available 24/7. It's like an on-demand @slax57. I modified his code review screenshot to get an idea of what it could look like, and I'm thrilled:

Paying Open-Source Maintainers For Their Work

There is one remaining problem: the training data (code reviews) isn't public content. Microsoft/GitHub doesn't have the right to use code reviews to train their AI.

GitHub, here is a proposal: Find the best open-source maintainers on your platform, ask them if you can use their past code reviews to train your AI, and pay them for it. They badly need it. The money you'll earn from the Copilot Code Reviewer will serve as retribution to the maintainers.

Since you'll get their approval, you may even use their name in the feature configuration. Here is what I'm dreaming of:

I, for one, would pay good money for this.

And as a maintainer of react-admin, a popular open-source project I've been developing for the last 5 years, I would also appreciate to get paid each time my AI avatar does a code review on another project.

Wait, did just I find a sustainable business model for open-source projects?

Conclusion

There are already many commercial products outside of GitHub offering AI-powered code review. To name a few:

But having GitHub bake in that feature would be a game changer for the open-source ecosystem altogether. I'm sure this is already in the works, so GitHub, when it's ready, please let me know!

Building a Timeline With React, Storybook, Material-UI, and React-Admin

Francois Zaninotto — Mon, 28 Jan 2019 09:57:23 +0000

For a customer project, I had to add a timeline of recent user actions in a backend application powered by react-admin. React-admin doesn't offer a Timeline component out of the box, so I had to implement it using pure React. In the process, I used a few coding tricks, so that makes a good tutorial.

User Story: A Timeline to Follow an Audit Trail

It all starts with a User Story for the Acme company, who is building a backend application to ease some of its business tasks. The customer requirements mention the end user problem that the story is supposed to solve, and that's:

As a manager, I want to monitor the activity of my team, so that I can detect any misdoing

After discussing with the customer, we agree that the best solution would be to record most actions of the team members in an audit trail, and to display these actions to the manager in reverse chronological order (the latest actions first) in a timeline.

UX: Don't Reinvent The Wheel

Normally, at that point, a UX expert should talk to the actual managers to design a perfect User Experience for the timeline. But fortunately, Jakob Nielsen, a famous UX practitioner, discovered a law that reduces UX work 90% of the time:

Users spend most of their time on other sites. This means that users prefer your site to work the same way as all the other sites they already know.

Jakob's Law

If Acme has to design a timeline for its managers, it should look like other timelines that the managers may already use. And they do see a lot of those on Twitter, Facebook, and others.

So no need to reinvent the wheel on the UX front: to design the Timeline UX, I blatantly copy the Facebook Feed page, adding just a touch of mine by grouping the events by day. Here is the resulting mockup:

Tip: Jakob's Law, together with 18 other UX laws, appear in the excellent Laws of UX website. I highly recommend it to get a basic understanding of UX principles.

Writing Fake Data

In order to write a mockup, I had to create fake data. It allowed me to discover a few corner cases that the timeline should handle:

Some events don't have an author. In that case, the event author should be named "Anonymous"
Some events can have a long label and may span across several lines. That also means that the title should use an ellipsis to avoid breaking the layout.
The event label doesn't seem to be easy to automate. For instance, the end user prefers to see "XXX commented" instead of "XXX added a comment".
The event day should use the user's locale. Fortunately, modern browsers can do that on their own.

Generating fake data is always a very important part of the design phase. It helps me to detect corner cases and to draft the data structure that should be used during development.

Designing Incomplete States

From a UX standpoint, the job is nearly done. I just have to design what the manager should see when the timeline doesn't contain events, and that may happen in three cases:

Loading: When the application has loaded and requested the events, but the server hasn't answered yet. This is a transitional state but it may last a few seconds.
Empty: When the server has answered with an empty list of events - probably at the early days of the manager's team.
Error: When the server timed out or responded with an error. Yes, that happens, too.

For the loading page, I use a "skeleton" screen:

And for the Empty page, an invite to start using the app:

For this particular application, errors are already handled globally (via a notification), so I don't need to design an Error page.

As for the UI, the customer has already chosen Material Design, so I'll just have to translate the mockups into some of the components showcased at material.io.

The Hard Part Is Naming Things

Based on the mockups, I could dive straight into code, but I like to take a moment and write things on a whiteboard first. That's because it's very easy to get lost in implementation details, and these details can lead to a bad code architecture. It's better to start from the domain, to list responsibilities, and to decide which part of the code will be responsible for each one. Yep, that's Domain Driven Design in practice.

So I draw boxes on the mockups to decompose the timeline into a tree structure of components, each with its own responsibility. I forbid myself to add a comment for each component to explain what it does. Instead, I spend as much time as needed to name the components explicitly, so that no further comment is necessary. That's because of Karlton's law:

There are only two hard things in Computer Science: cache invalidation and naming things.

Phil Karlton

So here we go:

Timeline
- TimelineLoaded
- EventList
  - EventItem
  - Avatar
- TimelineLoading
- TimelineEmpty

I test the names on another developer with the same domain knowledge to make sure that they all make sense, and carry the right meaning. Once the names are validated, I can start writing code.

Start By The Leafs

I have to develop 7 components. That's a lot. Where should I start?

I usually start by the deepest components in the tree structure, those with no children. That's for 4 reasons:

Leaf components are often presentational only. So I can quickly iterate with the customer on the design even before I've started to think about plugging them with actual data.
It's easier to test. A leaf component has no dependency and requires a small amount of data to render.
Leaf components are usually simpler (no need to think about fetching data, the "connected" components are higher in the chain), so I don't risk being blocked right from the start
I can design the shape of the data to be passed to the component with no assumption about the children

Overall, starting with the leaves helps to separate responsibilities/concerns in the right way

So let's start by the Avatar component. It relies on material-ui's Avatar, and uses the Gravatar service to display a user picture based on the user email. This is just a regular React.js component:

// in src/Avatar.js
import React from 'react';
import MuiAvatar from '@material-ui/core/Avatar';
import { withStyles } from '@material-ui/core/styles';
import md5 from 'blueimp-md5';

const styles = {
    avatar: {
        width: 25,
        height: 25,
    },
};

const AvatarView = ({ user, classes }) => (
    <MuiAvatar
        className={classes.avatar}
        src={
            user
                ? `https://www.gravatar.com/avatar/${md5(user.email)}?d=retro`
                : `https://www.gravatar.com/avatar/?d=mp`
        }
    />
);

const Avatar = withStyles(styles)(AvatarView);

export default Avatar;

Using Storybook to Develop In Isolation

Now, to render Avatar in isolation, I setup a Storybook and write a story:

// in src/Avatar.stories.js
import React from 'react';
import { storiesOf } from '@storybook/react';
import Avatar from './Avatar';

const userWithAvatar = {
    email: 'jitewaboh@lagify.com',
};

const userWithNoAvatar = {
    email: 'lelafeng@example.com',
};

storiesOf('Avatar', module)
    .add('basic', () => <Avatar user={userWithAvatar} />)
    .add('using fallback', () => <Avatar user={userWithNoAvatar} />)
    .add('anonymous', () => <Avatar />);

I can check that the Storybook displays an avatar, even when the user is undefined.

Avatar, check! The component contains no logic so I won't bother writing a unit test for it.

Start With a Story

Now, let's continue with the EventItem component. This time, I'll write the story first. It forces me to think about the shape of data the component should expect. For now, let's consider that the user data is included in the event:

// in src/EventItem.stories.js
import React from 'react';
import { storiesOf } from '@storybook/react';
import EventItem from './EventItem';

const event = {
    label: 'modified post "Hello World"',
    createdAt: '2019-03-11T12:34:56.000Z',
    author: {
        name: 'John Doe',
        email: 'jitewaboh@lagify.com',
    },
};

const anonymousEvent = {
    label: 'liked "Lorem Ipsum"',
    createdAt: '2019-03-11T12:34:56.000Z',
};

const eventWithLongName = {
    label:
        'commented "I don\'t agree. You should never try to do things this way, or you\'ll end up in a bad place."',
    createdAt: '2019-03-11T12:34:56.000Z',
    author: {
        name: 'Lela Feng',
        email: 'lelafeng@example.com',
    },
};

storiesOf('EventItem', module)
    .add('basic', () => <EventItem event={event} />)
    .add('anonymous', () => <EventItem event={anonymousEvent} />)
    .add('long event name', () => <EventItem event={eventWithLongName} />);

Then it's time to develop the EventItem itself. Nothing fancy here, just using standard material-ui code based on the ListItem component:

// in src/EventItem.js
import React from 'react';
import ListItem from '@material-ui/core/ListItem';
import ListItemText from '@material-ui/core/ListItemText';
import ListItemAvatar from '@material-ui/core/ListItemAvatar';
import { withStyles } from '@material-ui/core/styles';
import Avatar from './Avatar';

const styles = {
    truncate: {
        width: 500,
        whiteSpace: 'nowrap',
        overflow: 'hidden',
        textOverflow: 'ellipsis',
    },
};

const EventItemView = ({ event, classes }) => (
    <ListItem>
        <ListItemAvatar>
            <Avatar user={event.author} />
        </ListItemAvatar>
        <ListItemText
            primary={
                <div className={classes.truncate}>
                    <strong>
                        {event.author ? event.author.name : 'Anonymous'}
                    </strong>{' '}
                    {event.label}
                </div>
            }
            secondary={new Date(event.createdAt).toLocaleString()}
        />
    </ListItem>
);

const EventItem = withStyles(styles)(EventItemView);

export default EventItem;

The storybook helps me to validate the code.

Climbing the Component Tree

Now that EventItem is done, I can move up to the component tree and code the EventList component. I start by writing a story, and the test data:

// in src/EventList.stories.js
import React from 'react';
import { storiesOf } from '@storybook/react';
import EventList from './EventList';

const events = [
    {
        id: 1234,
        label: 'modified post "Hello World"',
        createdAt: '2019-01-10T17:15:56.000Z',
        author: {
            name: 'John Doe',
            email: 'jitewaboh@lagify.com',
        },
    },
    {
        id: 1233,
        label: 'created new post "Hello World"',
        createdAt: '2019-01-10T08:54:00.000Z',
        author: {
            name: 'John Doe',
            email: 'jitewaboh@lagify.com',
        },
    },
];

storiesOf('EventList', module)
    .add('basic', () => <EventList events={events} />)
    .add('empty', () => <EventList />);

I had to add an id field to each event because the list renders an array of EventItem component, and react expects a unique identifier for elements in a list. The list itself is straightforward:

// in src/EventList.js
import React from 'react';
import Card from '@material-ui/core/Card';
import List from '@material-ui/core/List';
import { withStyles } from '@material-ui/core/styles';
import EventItem from './EventItem';

const styles = {
    root: {
        width: 600,
    },
};

const EventListView = ({ events = [], classes }) => (
    <Card className={classes.root}>
        <List>
            {events.map(event => (
                <EventItem event={event} key={event.id} />
            ))}
        </List>
    </Card>
);

const EventList = withStyles(styles)(EventListView);

export default EventList;

Extracting Logic to Non-Component Code

Still moving up in the component hierarchy, I'm now considering the <TimelineLoaded> component. It is supposed to show events grouped by day. I assume the server will just send an array of events, so it's up to the client to aggregate them by day.

I could write that aggregation code in a component, but since it's pure JS code, and because I want to test it in isolation, I decide to write it in a standalone file, as pure functions.

// in src/groupByDay.js
const sortByDate = (a, b) => new Date(b).valueOf() - new Date(a).valueOf();

const getDayForEvent = event => {
    const date = new Date(event.createdAt);
    date.setMilliseconds(0);
    date.setSeconds(0);
    date.setMinutes(0);
    date.setHours(0);
    return date.toISOString();
};

const groupByDay = events => {
    const groups = events.reduce((days, event) => {
        const day = getDayForEvent(event);
        if (!days[day]) {
            days[day] = [];
        }
        days[day] = days[day].concat(event);
        return days;
    }, {});
    return {
        days: Object.keys(groups).sort(sortByDate),
        eventsByDay: groups,
    };
};

export default groupByDay;

Since it's plain JavaScript, this code is easy to test with Jest - no need to boot enzyme or react-testing-library:

// in src/groupByDay.test.js
import groupByDay from './groupByDay';

describe('groupByDay', () => {
    it('should aggregate events by day', () => {
        const events = [
            { createdAt: '2019-01-05T12:56:31.039Z', label: 'foo1' },
            { createdAt: '2019-01-05T09:12:43.456Z', label: 'foo2' },
            { createdAt: '2019-01-04T12:34:56.789Z', label: 'foo3' },
        ];
        expect(groupByDay(events)).toEqual({
            days: ['2019-01-04T23:00:00.000Z', '2019-01-03T23:00:00.000Z'],
            eventsByDay: {
                '2019-01-04T23:00:00.000Z': [
                    {
                        createdAt: '2019-01-05T12:56:31.039Z',
                        label: 'foo1',
                    },
                    {
                        createdAt: '2019-01-05T09:12:43.456Z',
                        label: 'foo2',
                    },
                ],
                '2019-01-03T23:00:00.000Z': [
                    {
                        createdAt: '2019-01-04T12:34:56.789Z',
                        label: 'foo3',
                    },
                ],
            },
        });
    });
});

This is the only unit test I'll need to write.

Most of the components I write are purely presentational (and require no test), because I'm used to extracting everything that can be tested into standalone functions. That way, I avoid the pitfalls of unit testing React components.

Keeping Presentational Components Small

The TimelineLoaded component should display events grouped by day. As before, I start by writing a Story - actually, most of the work is writing the test data. Fortunately, I already imagined test data earlier for the mockups, so it's just a matter of writing them in JSON.

// in src/TimelineLoaded.stories.js
import React from 'react';
import { storiesOf } from '@storybook/react';
import TimelineLoaded from './TimelineLoaded';

const events = [
    {
        id: 1234,
        label: 'modified post "Hello World"',
        createdAt: '2019-01-10T17:15:56.000Z',
        author: {
            name: 'John Doe',
            email: 'jitewaboh@lagify.com',
        },
    },
    {
        id: 1233,
        label: 'created new post "Hello World"',
        createdAt: '2019-01-10T16:34:00.000Z',
        author: {
            name: 'John Doe',
            email: 'jitewaboh@lagify.com',
        },
    },
    {
        id: 1232,
        label:
            'commented "I don\'t agree. You should never try to do things this way, or you\'ll end up in a bad place."',
        createdAt: '2019-01-09T15:53:56.000Z',
        author: {
            name: 'Lela Feng',
            email: 'lelafeng@example.com',
        },
    },
    {
        id: 1231,
        label: 'deleted comment "Totally."',
        createdAt: '2019-01-09T11:04:56.000Z',
        author: {
            name: 'Brandon Hood',
            email: 'brandon@example.com',
        },
    },
    {
        id: 1230,
        label: 'liked "Lorem Ipsum"',
        createdAt: '2019-01-09T09:12:56.000Z',
    },
];

storiesOf('TimelineLoaded', module)
    .add('basic', () => (
        <TimelineLoaded events={events.slice(0, -1)} total={5} />
    ))
    .add('fully loaded', () => <TimelineLoaded events={events} />)
    .add('empty', () => <TimelineLoaded />);

Once again, there is very little logic in the <TimelineLoaded> component below. There are only two conditions testing for limit cases (empty event list, which is not normal, and fully loaded event list, which is normal). The rest is presentational.

// in src/TimelineLoaded.js
import React from 'react';
import Typography from '@material-ui/core/Typography';
import Button from '@material-ui/core/Button';
import { withStyles } from '@material-ui/core/styles';

import EventList from './EventList';
import groupByDay from './groupByDay';

const styles = {
    root: {
        width: 600,
        margin: 'auto',
    },
    day: {
        marginBottom: '1em',
    },
};

const getDayString = date =>
    new Date(date).toLocaleDateString(undefined, {
        weekday: 'long',
        year: 'numeric',
        month: 'long',
        day: 'numeric',
    });

const TimelineLoadedView = ({
    events = [],
    handleLoadMore,
    total,
    classes,
}) => {
    const { days, eventsByDay } = groupByDay(events);
    if (days.length === 0) {
        return (
            <Typography color="error">
                Error: This list should not be empty.
            </Typography>
        );
    }
    return (
        <div className={classes.root}>
            {days.map(day => (
                <div key={day} className={classes.day}>
                    <Typography variant="subheading" gutterBottom>
                        {getDayString(day)}
                    </Typography>
                    <EventList events={eventsByDay[day]} />
                </div>
            ))}
            {events.length < total && (
                <Button variant="contained" onClick={handleLoadMore}>
                    Load more events
                </Button>
            )}
        </div>
    );
};

const TimelineLoaded = withStyles(styles)(TimelineLoadedView);

export default TimelineLoaded;

Keeping components small makes it easy to reason about code.

Note that I haven't written a single line of code for fetching the events yet. And therefore, all the code above is pure react and material-ui. No Redux, no react-admin.

Managing UI State

Now it's time to deal with the <Timeline> component. This component fetches the data, and decides to display either one of the three components below:

<TimelineLoading>
<TimelineLoaded>
<TimelineEmpty>

Tip: I haven't included the code for <TimelineLoaded> and <TimelineEmpty> in this tutorial, but you can find them in the source, linked at the end of the tutorial.

My first reflex was to use react-admin's <List> component, letting react-admin fetch the events. That way, I'd just have to decide which <TimelineXXX> component to render based on the data fetched by react-admin. That means I initially wrote the Timeline component as follows:

// in src/Timeline.js
import React from 'react';
import { List } from 'react-admin';

import TimelineLoaded from './TimelineLoaded';
import TimelineLoading from './TimelineLoading';
import TimelineEmpty from './TimelineEmpty';

export const TimelineView = ({ ids, data, total, loadedOnce }) =>
    !loadedOnce ? (
        <TimelineLoading />
    ) : ids.length > 0 ? (
        <TimelineLoaded
            events={ids.map(id => data[id])}
            total={total}
        />
    ) : (
        <TimelineEmpty />
    );

const Timeline = props => (
    <List {...props}>
        <TimelineView />
    </List>
);

export default Timeline;

As a matter of fact, this script contains two components: a view (TimelineView) and a controller (Timeline).

The TimelineView component is independent of react-admin, so it's easy to test with Storybook. I reused the fake timeline data from the TimelineLoaded story:

// in src/Timeline.stories.js
import React from 'react';
import { storiesOf } from '@storybook/react';
import { TimelineView } from './Timeline';
import { events } from './TimelineLoaded.stories.js';

storiesOf('Timeline', module)
    .add('loading', () => <TimelineView />)
    .add('loaded', () => (
        <TimelineView
            ids={events.map(event => event.id)}
            data={events.reduce(
                (data, event) => ({ ...data, [event.id]: event }),
                {}
            )}
            total={10}
            loadedOnce={true}
        />
    ))
    .add('empty', () => <TimelineView ids={[]} data={{}} loadedOnce={true} />);

Integrating With React-Admin

In the Timeline component, react-admin's <List> component fetches, computes and injects the ids, data, total, and loadedOnce props to its child.

To test Timeline, I have to use is as the list prop of the <Resource name="events" /> in react-admin:

// in src/App.js
import React, { Component } from 'react';
import { Admin, Resource } from 'react-admin';

import dataProvider from './dataProvider';
import Timeline from './Timeline';

const App = () => (
    <Admin dataProvider={dataProvider}>
        <Resource name="events" list={Timeline} />
    </Admin>
);

export default App;

I can test it visually with Storybook:

// in src/App.stories.js
import React from 'react';
import { storiesOf } from '@storybook/react';
import App from './App';

storiesOf('App', module).add('basic', () => <App />);

That works fine: the <TimelineLoading> appears first (while the <List> is fetching the events from the dataProvider), then the events appear in the <TimelineLoaded>.

But there is UI a problem with this approach: react-admin's <List> renders a material-ui <Paper>, so the <Timeline> shows a paper within a paper. Not satisfactory.

Using React-Admin ListController Component To Customize The List Layout

So I decided to go a bit deeper and to use the controller part of react-admin's <List> but not the UI. In fact, react-admin does all the data fetching in a component called <ListController>, which delegates the rendering to its child (using the render props pattern). So I can overcome the "paper in paper" problem by writing the following code:

// in src/Timeline.js
import React from 'react';
import { ListController } from 'react-admin';

// ...

const Timeline = props => (
    <ListController {...props}>
        {controllerProps => <TimelineView {...controllerProps} />}
    </ListController>
);

That's a bit too drastic because the <List> component used to take care of the page title. Using <ListController> only, the page title is empty. So I need one more change to make it work, and that's using react-admin's <Title> component:

// in src/Timeline.js
import React from 'react';
import { ListController, Title } from 'react-admin';

// ...

const Timeline = props => (
    <ListController {...props}>
        {controllerProps => (
            <>
                <Title title="Events" />
                <TimelineView {...controllerProps} />
            </>
        )}
    </ListController>
);

Now the UI displays the timeline over a gray background instead of a paper. From a UI point of view, that's a success!

Making the Pagination Work

The "Load more events" button has no effect for now. The <TimelineLoaded> component expects a handleLoadMore prop that I didn't include yet. I could use the controllerProps that the <ListController> prepares - they include a page and a setPage prop.

But <ListController> replaces the current page by the next one, whereas in a timeline, when the user clicks on "Load more events", they expect to see the new events appear in addition to the previous ones. I have to use a local state trick to keep relying on <ListController>. In the process, I'm obliged to turn <TimelineView> into a class component:

// in src/Timeline.js
import React, { Component } from 'react';
import { ListController, Title } from 'react-admin';

import TimelineLoaded from './TimelineLoaded';
import TimelineLoading from './TimelineLoading';
import TimelineEmpty from './TimelineEmpty';

class TimelineView extends Component {
    state = {
        events: [],
        latestId: null,
    };

    static getDerivedStateFromProps(props, state) {
        const { ids, data } = props;
        const latestId = ids[ids.length - 1];
        if (latestId !== state.latestId) {
            const newEvents = ids.map(id => data[id]);
            return {
                events: state.events.concat(newEvents),
                latestId,
            };
        }

        return null;
    }

    handleLoadMore = () => {
        this.props.setPage(this.props.page + 1);
    };

    render() {
        const { events } = this.state;
        const { total, loadedOnce } = this.props;
        return !loadedOnce ? (
            <TimelineLoading />
        ) : events.length > 0 ? (
            <TimelineLoaded
                events={events}
                total={total}
                handleLoadMore={this.handleLoadMore}
            />
        ) : (
            <TimelineEmpty />
        );
    }
}

const Timeline = props => (
    <ListController {...props}>
        {controllerProps => (
            <>
                <Title title="Events" />
                <TimelineView {...controllerProps} />
            </>
        )}
    </ListController>
);

export default Timeline;

The "Load more events" button now works, but with a caveat. If the user clicks on "Load more events", the page increments from 1 to 2, and the events for page 2 appear below the initial events. But, if the user refreshes the list, only the events from page 2 are rendered on screen. Why is that?

<ListController> keeps track of the current page, so that next time the user reloads a list, they see the same page they had on screen before leaving the list. So after loading more events, the <ListController> loads page 2 by default. My trick doesn't really work.

Using a Custom List Controller

In fact, <ListController> does a lot of things that I don't need. It handles filters, custom sort order, and the query string. As it doesn't handle pagination the way I need, perhaps I can replace ListController by a custom component of my own?

There are two things that <ListController> does that my new component must replicate:

dispatch a Redux action (crudGetList) to fetch the events
grab the data and ids from the state.

Well, it shouldn't be too difficult to write, is it?

// in src/Timeline.js
import React, { Component } from 'react';
import { connect } from 'react-redux';
import { Title, crudGetList } from 'react-admin';
import TimelineLoaded from './TimelineLoaded';
import TimelineLoading from './TimelineLoading';
import TimelineEmpty from './TimelineEmpty';

export class Timeline extends Component {
    page = 1;
    constructor(props) {
        super(props);
        this.state = {
            events: props.ids.map(id => props.data[id]),
            latestId: props.ids[props.ids.length - 1],,
        };
    }

    updateData = () => {
        this.props.crudGetList(
            'events',
            { page: this.page, perPage: 10 },
            { field: 'id', order: 'DESC' }
        );
    };

    componentDidMount() {
        this.updateData();
    }

    componentDidUpdate(prevProps, prevState) {
        if (this.props.ids !== prevProps.ids) {
            const { ids, data } = this.props;
            const latestId = ids[ids.length - 1];
            if (latestId && latestId !== prevState.latestId) {
                const newEvents = ids.map(id => data[id]);
                this.setState(state => ({
                    events: state.events.concat(newEvents),
                    latestId,
                }));
            }
        }
    }

    handleLoadMore = () => {
        this.page = this.page + 1;
        this.updateData();
    };

    render() {
        const { events } = this.state;
        const { total, loadedOnce } = this.props;
        return (
            <>
                <Title title="Events" />
                {!loadedOnce ? (
                    <TimelineLoading />
                ) : events.length === 0 ? (
                    <TimelineEmpty />
                ) : (
                    <TimelineLoaded
                        events={events}
                        total={total}
                        handleLoadMore={this.handleLoadMore}
                    />
                )}
            </>
        );
    }
}

Timeline.defaultProps = {
    ids: [],
    data: {},
    crudGetList: () => null,
};

const mapStateToProps = state => ({
    ids: state.admin.resources.events.list.ids,
    data: state.admin.resources.events.data,
    total: state.admin.resources.events.list.total,
    loadedOnce: state.admin.resources.events.list.loadedOnce,
});

export default connect(
    mapStateToProps,
    { crudGetList }
)(Timeline);

And without changing the application code, it works:

import React, { Component } from 'react';
import { Admin, Resource } from 'react-admin';

import dataProvider from './dataProvider';
import Timeline from './Timeline';

const App = () => (
    <Admin dataProvider={dataProvider}>
        <Resource name="events" list={Timeline} />
    </Admin>
);

export default App;

Acute observers may notice a little problem, though. When a user clicks on "Load More", then browses to another page, then browses back to the Timeline, they briefly see the events of page 2 before seeing the events of page 1. This is because when the Timeline mounts, it grabs the list of events from the Redux store. The last time the Timeline was mounted, it was for page 2. Therefore, the events from page 2 appear while page 1 is being fetched.

To fix this problem, I simply reset the list of events in the store when the Timeline unmounts:

export class Timeline extends Component {
    // ...
    componentWillUnmount() {
        this.page = 1;
        this.updateData();
    }
}

Now the User Experience is flawless.

This version of the <Timeline> is clearer because it only uses Redux. It also shows that it's possible to replace a component as central as <List> with a component of your own. React-admin was in fact designed to allow an easy replacement of any of its components. React-admin tries to do one thing right and to let you use your own components when a use case requires something more specific.

This component also uses very little of react-admin - in fact, just the Redux store and one action creator. but these are the core of react-admin, the skeleton if you prefer. In many cases, when I want to build something specific with react-admin, I end up using only that core. Knowing react-admin core will set you free to do whatever you want.

Using Internationalisation

I was a bit too optimistic when creating the fake events. I thought that the server could return event labels, as follows:

const events = [
    {
        id: 1234,
        label: 'modified post "Hello World"',
        createdAt: '2019-01-10T17:15:56.000Z',
        author: {
            name: 'John Doe',
            email: 'jitewaboh@lagify.com',
        },
    },
    {
        id: 1233,
        label: 'created new post "Hello World"',
        createdAt: '2019-01-10T16:34:00.000Z',
        author: {
            name: 'John Doe',
            email: 'jitewaboh@lagify.com',
        },
    },
    ...
];

But the customer wants the application to be usable in several languages, and to handle i18n logic on the frontend side. That means that the API must return events in a language agnostic way, and they actually look like the following:

const events = [
    {
        id: 1234,
        object: 'post',
        objectName: 'Hello World',
        type: 'modify',
        createdAt: '2019-01-10T17:15:56.000Z',
        author: {
            name: 'John Doe',
            email: 'jitewaboh@lagify.com',
        },
    },
    {
        id: 1233,
        object: 'post',
        objectName: 'Hello World',
        type: 'create',
        createdAt: '2019-01-10T16:34:00.000Z',
        author: {
            name: 'John Doe',
            email: 'jitewaboh@lagify.com',
        },
    },
    ...
];

So the EventItem can no longer use the event.label data. I chose to use the react-admin translation system to turn the structured event data into a localized string. The idea is to generate a translation key for an event, e.g. event.post.modify, or event.post.create, and to turn this identifier into a language-specific string in the locale dictionaries.

import React from 'react';
import ListItem from '@material-ui/core/ListItem';
import ListItemText from '@material-ui/core/ListItemText';
import ListItemAvatar from '@material-ui/core/ListItemAvatar';
import { withStyles } from '@material-ui/core/styles';
+import { translate } from 'react-admin';
import Avatar from './Avatar';

// ...

-const EventItemView = ({ event, classes }) => (
+const EventItemView = ({ event, translate, classes }) => (
    <ListItem>
        <ListItemAvatar>
            <Avatar user={event.author} />
        </ListItemAvatar>
        <ListItemText
            primary={
                <div className={classes.truncate}>
                    <strong>
                        {event.author ? event.author.name : 'Anonymous'}
                    </strong>{' '}
-                   {event.label}
+                   {translate(`event.${event.object}.${event.type}`, {
+                       name: event.objectName,
+                   })}
                </div>
            }
            secondary={new Date(event.createdAt).toLocaleString()}
        />
    </ListItem>
);

-const EventItem = withStyles(styles)(EventItemView);
+const EventItem = translate(withStyles(styles)(EventItemView));

export default EventItem;

I add the translation in the react-admin dictionary files:

// in src/i18n/en.js
import englishMessages from 'ra-language-english';

export default {
    ...englishMessages,
    event: {
        post: {
            create: 'created a new post "%{name}"',
            modify: 'modified post "%{name}"',
        }
    }
}

Variable substitution in translation strings allows the translation to look natural.

Conclusion

It took me about three hours to code the Timeline and plug it to react-admin. You can find the final code on GitHub, in the marmelab/timeline-react-admin repository. I was really happy with how little react-admin code I had to write - in fact, most of my code is pure React. I used Redux in the Timeline component and react-admin's i18n utility in EventItem.

React-admin never got in the way: when I understood that the <List> component didn't fit with the user story, I replaced it in no time.

The only difficulty was to properly assign responsibilities to each component, and handle Timeline state based on the data.

I hope this tutorial helps you design your own custom list components, and provide a better user experience than react-admin's default <Datagrid> component.

DEV Community: Francois Zaninotto

New client-side hooks coming to React 19

use(Promise)

use(Context)

Form Actions

useFormState

useFormStatus

useOptimistic

Bonus: Async Transitions

Conclusion

Documentation: The Key Enabler For Open-Source Success

React-admin Docs In A Nutshell

Why Documentation Matters

Doc Pitfalls To Avoid

13 Tips For Writing Great Documentation

Write Once, Maintain Forever

Going Further

Conclusion

Anatomy Of A Profitable Open-Source Project

Usage and Popularity

Key Performance Indicators

Revenue And Costs

Conclusion

React Without useEffect

A Complete React App Without useEffect

Declarative Data Fetching

Declarative Data Sync

But That Doesn't Work In My Case

Conclusion

Using Copilot to Review Code And Fund Open-Source Projects

Copilot Only Gets You So Far

Peer Code Reviews Are A Blessing

Using GPT3 to Review Code

Paying Open-Source Maintainers For Their Work

Conclusion

Building a Timeline With React, Storybook, Material-UI, and React-Admin

User Story: A Timeline to Follow an Audit Trail

UX: Don't Reinvent The Wheel

Writing Fake Data

Designing Incomplete States

The Hard Part Is Naming Things

Start By The Leafs

Using Storybook to Develop In Isolation

Start With a Story

Climbing the Component Tree

Extracting Logic to Non-Component Code

Keeping Presentational Components Small

Managing UI State

Integrating With React-Admin

Using React-Admin ListController Component To Customize The List Layout

Making the Pagination Work

Using a Custom List Controller

Using Internationalisation

Conclusion

A Complete React App Without `useEffect`