DEV Community: Ely Lucas

Introducing ts-dash: A Quick and Simple TypeScript Project Creator

Ely Lucas — Wed, 18 Feb 2026 17:46:05 +0000

The Itch

Lately I've been creating a lot of throwaway TypeScript projects. You know that feeling. You have an idea for a quick script, a small API, or just want to try something out in TypeScript. So you create a folder, run npm init, install TypeScript, set up a tsconfig.json, configure your build step, add a watch script, try a bunch of different options to get the module system right, and by the time you're done you've forgotten what you were trying to build in the first place.

I've done this dance a hundred times. And every time, I think "I should really automate this." So I finally did.

The amazing part? I did it all in Claude Code (right after Opus 4.6 dropped), literally going from idea to a working scaffolding tool in about an hour. It was a blast. I told Claude exactly what I wanted, and it generated the entire project for me. I just had to tweak a few things here and there.

create-ts-dash

create-ts-dash is a simple scaffolding tool that gets you from zero to a working TypeScript project in one command:

npm create ts-dash my-app

That's it. You get a clean TypeScript project with sensible defaults, ready to go. No boilerplate fatigue, no decision paralysis. The project is created from scratch each time, so you always get the latest package versions.

What You Get

Every project comes with:

TypeScript with a strict config (because we're not animals)
tsx for running TypeScript directly with file watching
ESM modules configured out of the box
Git initialized with a .gitignore

Need a Web Server?

If you're building an API or a server, create-ts-dash lets you pick from three frameworks:

Express — the one you already know
Fastify — fast and low overhead
Hono — lightweight and ultrafast

Optional Tooling

You can also opt into:

ESLint + Prettier for linting and formatting
Vitest for testing

Nothing is forced on you. Pick what you need, skip what you don't.

"Doesn't This Already Exist?"

Yes. Probably. Almost certainly. I didn't do extensive research, and I don't care. Sometimes you want to build something that works exactly the way you think it should. Something where you know every line of code because you wrote it. Something that scratches your specific itch.

I built create-ts-dash for me. If it's useful to you too, that's awesome. If you prefer something else, that's cool too. The world has room for another scaffolding tool.

Try It Out

# with npm
npm create ts-dash my-app

# with yarn
yarn create ts-dash my-app

# with pnpm
pnpm create ts-dash my-app

# with bun
bun create ts-dash my-app

Or run it without a project name for interactive mode:

npm create ts-dash

Check out the repo at github.com/elylucas/create-ts-dash, give it a spin, and let me know what you think.

Happy coding!

Introducing the New Overlay Hooks for Ionic React

Ely Lucas — Mon, 09 Aug 2021 21:48:10 +0000

Hello Friends! We know everyone is excited about the new features in Ionic Framework 6.0 beta, but that doesn't mean we're done with V5! In Ionic React 5.6, we packaged up a new set of hooks for controlling our overlay components that we think you might like. What is an overlay you ask? It’s the term we give components that display over your current content, such as alerts, modals, toasts, etc.

In this post, I’m going to go over how to use the new hooks to display these components in your apps. But first, let's do a quick recap on how overlays worked before, and some of the challenges that you might encounter with them.

Overlay Components

Each of the overlays has a React component that is exported from @ionic/react, such as IonAlert and IonLoading. These components take a prop called isOpen, which determines if the overlay should be displayed or not:

<IonAlert
  isOpen={showAlert}
/>

These components are great and they aren’t going away. The new hooks don't deprecate them in any way. However, there's some ceremony you have to observe to use them.

First, managing the state that handles the isOpen prop could be a challenge. If the state was contained in the component that the overlay was in, then it was no problem (like a local state variable from useState). However, if the action to display the overlays was in a different part of the app, then you needed to use some state management technique or library to pass the isOpen prop along.

Second, each of the Overlay components required you to provide an onDidDismiss callback that would flip the isOpen prop back to false in case the overlay dismissed itself somehow. Not overriding it would cause isOpen to stay true, and if your app tried to show the overlay again, then you would be setting true to true, and Ionic wouldn’t detect the change and, thus, wouldn't display it again.

<IonAlert
  isOpen={showAlert}
  message='Hello there friend'
  onDidDismiss={() => setShowAlert(false)}
/>

A third challenge was that it was difficult to display an overlay from outside of your component; for instance, if you wanted to display an alert when an API request failed. Ionic Angular had controller instances you could import to use in services to display overlays. In React, this was more difficult to do.

The new overlay hooks in Ionic React 5.6 help with all these scenarios.

Overlay Hooks

The goal of the overlay hooks was to reduce this process and to make the usage of the overlays feel more natural for those writing functional React components.

To get started with the hooks, you import the hook for the overlay you want to use from @ionic/react like so:

import { useIonAlert } from '@ionic/react'

Next, in your functional component, you call the hook to get back the show and hide methods, which get returned in an array similar to how useState returns its members. We choose the array method of destructuring so naming the methods is easier:

const [showAlert, hideAlert] = useIonAlert();

Most overlays dismiss themselves when the user is done interacting with them, so you won’t need the hide method for most scenarios.

Then to display the overlay, you call the show method:

showAlert('Hello!');

The alert will dismiss itself after the user clicks the "Ok" button. You don’t need to worry about doing any additional work when the overlays go away.

Most of the overlay hooks have options that you can pass to them. The more common options can be passed in as additional parameters. For instance, the toast overlay's show method also takes the time to display the toast as its second parameter:

showToast('Hello from a toast!',  3000);

This will display the toast for three seconds, and then the toast will dismiss itself.

More options can be sent by passing in an object instead of the separate parameters:

showToast({
  buttons: [{ text: 'hide', handler: () => hideToast() }],
  message: 'Hello, click hide to dismiss',
  onDidDismiss: () => console.log('dismissed')              
})

React hooks can be used in other hooks as well. Because of this, it's possible to display an overlay from within other hooks, such as one responsible for fetching some data. Here is a sample custom hook to fetch a customer that displays a toast when the request fails:

const useCustomer = (customerId: number) => {
  const [customer, setCustomer] = useState<Customer>();
  const [showToast] = useIonToast();
  useEffect(() => {
    fetchCustomer();
    async function fetchCustomer() {
      try {
        const response = fetch(`myapi.com/customers/${customerId}`);
        const data = await (await response).json();
        setCustomer(data);
      } catch {
        showToast({
          message: 'Oops, unable to get customer',
          color: 'warning',
          buttons: [{ icon: close }],
        });
      }
    }
  }, [customerId, showToast]);
  return customer;
};

More Info

To learn more about the new hooks, visit our guide on using overlays in Ionic React, and check out the docs for each of the overlay components for usage examples:

Let us know in the comments down below if you have any feedback, and until next time, happy coding!

How to Reduce the Number of Renders in an Ionic React App

Ely Lucas — Thu, 28 Jan 2021 15:45:05 +0000

Hello friends!

Welcome to this first article in a series that I plan on doing around quick tips for routing in Ionic React.

To kick this series off, I'm going to answer one of the top questions I get, and that's "Why do my Ionic Pages render so much?"

For starters, you shouldn't be overly concerned with multiple renders. During the render phase, React will build up a representation of your component in what is called the Virtual DOM. Building this VDOM is relatively cheap. Afterward, React will compare the VDOM to what is in the actual DOM, and it will only do the costly DOM updates if there are actual changes.

This means that if your component renders again, but there aren’t any changes, then the cost is minimal.

However, there are a couple of drawbacks to rendering too much. First, React must construct the VDOM and run its diffing algorithm for each render call. While this is highly optimized and fast, doing so is wasteful if the component doesn’t need to update. Second, if you have costly code in the render method, it will get run each time.

Also, if you are like me, it can drive you bonkers.

Therefore, trying to cut down on the number of renders is a micro-optimization, but sometimes it’s one worth taking.

In this article, we will take a look at why render gets called multiple times, and then I'll show you some techniques you can use in your own apps to help reduce them.

Project Setup

If you want to follow along, start up a new Ionic React app using the Ionic CLI:

ionic start RenderTest tabs --type=react

And in the Tab1.tsx file, add a log statement inside of the function so we can see each time the component is rendered:

const Tab1: React.FC = () => {
  console.log('tab1 render');

  return (
    <IonPage>
      {...}
    </IonPage>
  );
};

Fire up the app with ionic serve, and you will see that, on initial load, the Tab1 page renders twice:

However, if you click around on the tabs, you will see that Tab1 renders 3-4 times each time you switch a tab! What's going on here?

Why you render so much?

Every page in an Ionic React app is wrapped with an IonPage component. The IonPage not only provides some div containers for holding your page and styles around it, but it is also very important when it comes to doing page transitions.

There is some semi-complicated logic that goes on in the background in regards to getting a reference to these IonPages when they are transitioned to and from. Unfortunately, to get the reference, we have to wait until the component mounts, then grab the reference, and store that reference in context. This all happens in the IonRouterOutlet component, but when this component renders, it often causes its children (your routes and IonPages) to render along with it.

This is why you might see an IonPage render two or three times when it is displayed the first time.

Next, you might notice that some pages might render when they are not even in the current view.

To provide some of the smooth transitions and to maintain the state of views that you left but might come back to, we don't actually unmount your component in some scenarios (like navigating between tabs). Instead, when your page transitions out of view, we hide it via CSS. The component is still mounted and can still render. Therefore, if the component gets any new props passed into it, it will render.

By default, the routes are setup to pass in the your IonPage in the component prop of a route, like so:

<Route path="/tab1" component={Tab1} exact={true} />

When using the component prop, React Router will pass in some props on your behalf, like location and history. Each time you make a navigation change, these route props will change, which will cause all your IonPages that are currently mounted to render again.

This can get a bit out of hand, so let’s take a look at a few strategies to cut down on the excessive renders.

Optimizing the renders

So there are two main culprits here. Parent components that are rendering that cause its children to render, and new props being passed in via routing that causes another render.

Let's deal with parent components rendering first.

Component Memoization

In React class-based components, we were able to finely control when components would render with the shouldComponentUpdate lifecycle method. This method would receive the new props/state coming in, which we could compare to the old props/state and determine if we want our component to call its render method. Or, even better, we could inherit from React.PureComponent and let React take care of this logic for us.

This would make it so that your component would only update if its props or state change, and ignore any updates from the parent component rendering.

To accomplish something similar in a React Functional Component (FC), we can wrap our FC in React.memo, which will memoize your component and store a cached version of it based on the props that are passed into it.

To do so, I like to wrap the FC as its being exported with React.memo like so:

export default React.memo(Tab1);

You should notice that now the number of renders is cut down quite a bit when you navigate between the tabs.

Using React.memo is a good way to cut down on needless renders, however, take care when doing this, as you are basically trading fewer renders for memory consumption.

Route Setup

Next, let’s modify our routes so that React Router no longer passes in the Route Component props into our Tab1 page.

In the route setup, we are using the component prop, and React Router will pass in all the route props every time there is a change in navigation.

As of React Router 5.1, there is a new method to specify which component to render when the route matches, and this method is encouraged going forward.

The new method is to pass your component in as a child to the route like so:

<Route path="/tab1" exact={true}>
  <Tab1 />
</Route>

Now, if you check the logs, you will see that the Tab1 page only renders once on its initial load, and has no additional renders when navigating between the tabs. Nice 🎉!

"But what if I need the routing props in my component?" I hear you ask.

React Router has you covered there as well. There are several new React Hooks available that you can use to get access to the same props that were passed in before, namely useParams, useLocation, and useHistory. So if you had a route setup to get an id param from the path, you would access it like so:

/* The Route: */
<Route path="/tab1/:id" exact={true}>
  <Tab1 />
</Route>

/* And inside the Tab1.tsx function: */
const params = useParams<{id: string}>();
// do something with params.id

Wrapping Up

With just a few quick optimizations, we were able to cut down the renders from many times on page navigation, to just a single time when the IonPage first loads. Not too shabby!

Got any comments or want to see me cover something around Ionic React in the future? Hit me up in the comments below or catch me on Twitter @elylucas.

Happy coding!

How to Confirm Leaving a Page in Ionic React with React Router

Ely Lucas — Fri, 09 Oct 2020 14:00:42 +0000

Have you ever been in the middle of an important task on a page, like filling out a form, and accidentally left and lost all your work? That bites!

And it's a bad experience for your users, especially on mobile.

A typical technique is to confirm with the user if they do want to leave the page with a confirmation dialog. In this post, I'll show you how to do so in an Ionic React application, and how you can customize the confirmation UI to fit your particular app. Let's go!

Using React Router's Prompt Component

An Ionic React application uses React Router for all of its navigation, and, fortunately, React Router has good support for prompting the user on navigation with their Prompt component. With Prompt, a confirmation box pops up asking the user if they want to leave the page. If they click yes, the navigation takes place, and if they click no, they are left on the current page.

The Prompt component takes two props, a message to display, and a when boolean to activate it.

Here is a simple IonPage with a form that utilizes the Prompt component:

const Tab1: React.FC = () => {
  const [text, setText] = useState('');

  useIonViewWillLeave(() => {
    setText('');
  });
  return (
    <IonPage>
      <IonHeader>
        <IonToolbar>
          <IonTitle>Tab 1</IonTitle>
        </IonToolbar>
      </IonHeader>
      <IonContent fullscreen>
        <IonInput
          value={text}
          placeholder="Name"
          onIonChange={(e) => {
            setText(e.detail.value!);
          }}
        ></IonInput>

        <IonButton
          expand="block"
          onClick={() => {
            setText('');
          }}
        >
          Submit
        </IonButton>
        <Prompt
          when={!!text}
          message="You have unsaved changes, are you sure you want to leave?"
        />
      </IonContent>
    </IonPage>
  );
};

Prompt is imported from 'react-router'

To determine if the form is "dirty" (if the form has been modified), we check to see if the IonInput has a value or not. This is a simple method, and you will probably need to expand on the concept in your app. Many form libraries provide a way to determine if the form has been modified as well.

In the useIonViewWillLeave hook, when a user leaves the page, we set the value of text back to a blank string to "reset" the form. This keeps the prompt from showing on other pages.

Now, if we try to leave the form, by say, accidentally tapping one of the other tab buttons, we get a nice confirmation:

This is fairly functional as is. The confirm dialog on mobile devices looks decent, but if you want to customize the UI, we will dive into that next.

Customizing the Confirm UI

Instead of showing the built-in confirm dialog that comes with the browser, you might want to display something a bit more custom to match the look and feel of your app. To change it up, we will use an IonAlert with custom buttons for the confirmation.

React Router provides a way to tie into the process by passing in a getUserConfirmation prop when setting up the router. In an Ionic app, we use IonReactRouter and we can pass this prop here and the router will, in turn, pass the prop back down to the underlying ReactRouter.

This prop excepts a function that gets passed in the message to display, as well as a callback. The callback takes a boolean parameter to indicate if the route navigation should happen or not. We'll add it to the main App.tsx page, where the routing is set up:

<IonReactRouter
  getUserConfirmation={(message, callback) => {

  }}
>

When getUserConfirmation is called, we want to display an IonAlert overlay with the message that was passed in. We will use a state variable to store the message. Also, we utilize a ref object to hold a reference to the callback that will be used in the alert:

const [leaveConfirmMessage, setLeaveConfirmMessage] = useState<string>();
const confirmCallback = useRef<(ok: boolean) => void>();

And to set them in the getUserConfirmation:

<IonReactRouter
  getUserConfirmation={(message, callback) => {
    setLeaveConfirmMessage(message);
    confirmCallback.current = callback;
  }}
>

Next, we add the IonAlert towards the bottom of the page, but before the closing </IonReactRouter>:

<IonAlert
  isOpen={!!leaveConfirmMessage}
  message={leaveConfirmMessage}
  buttons={[
    {
      text: "No",
      handler: () => {
        confirmCallback.current && confirmCallback.current(false);
      },
    },
    {
      text: "Yes",
      handler: () => {
        confirmCallback.current && confirmCallback.current(true);
      },
    },
  ]}
  onDidDismiss={() => setLeaveConfirmMessage(undefined)}
/>

To determine if the alert is shown, we check if the confirm message has a value, and then set the message back to undefined when the alert is dismissed. In the buttons, we use the ref we set up to invoke the callback function, passing true when the user clicks "Yes", and false when "No" is clicked.

And that's it! We use the Prompt component as we did before in any page we want to use this custom UI. No changes are needed in our form page.

Using the Browsers `beforeUnload` Event

One last thing we need to cover, which is what happens when the user tries to move away from the page outside of our app, like via the back button or changing the URL manually?

We can use the browser's beforeUnload event for this, though it is not customizable, browser support is limited, and it requires a bit more code. However, setting it up will give our users whose browsers support it extra protection if they, say, accidentally refresh their page.

Back in the page with the form, we will add a useEffect hook to monitor the text state. We set the onbeforeunload method on the window object to a function that returns true when the text has a value, and when the effect changes, set it null to turn it back off:

useEffect(() => {
  if (text) {
    window.onbeforeunload = () => true;
  }
  return () => {
    window.onbeforeunload = null;
  };
}, [text]);

This could also be abstracted into its own component or hook for reuse.

Wrapping up

Adding some safeguards to prevent your users from accidentally leaving a page while they are performing an important task is, thankfully, pretty straight-forward in an Ionic React app thanks to the built-in support in React Router.

I put together a demo app you can take a look at, feel free to check it out. Also, hit me up on twitter @elylucas or in the comments below if you have any questions.

Happy Coding!

How to CSS in Ionic React with Styled Components

Ely Lucas — Thu, 10 Sep 2020 15:04:29 +0000

When it comes to writing CSS in a React app, there are numerous options to choose from. And many people coming to Ionic React for the first time often wonder what the best approach is. The React library itself doesn't have an opinion about how styles are used in a React app, so where does one turn?

By default, an Ionic React application uses plain old CSS files that are included in their corresponding components. This is a tried and true approach that has been around since the beginning of web development. However, this approach doesn't fit in well with the idea of writing encapsulated (yet extensible) components in React.

One of the major drawbacks to the plain old CSS approach is that there is no built-in mechanism to scope the CSS to your particular page or component. This could lead to unintended side effects where styles bleed out of their components and affect other elements.

Other areas of concern crop up around how to extend the style of a component, and how to apply themes to a component with only plain CSS.

Fortunately, there is a vibrant community in the React ecosystem that has solved a few of these issues. And since an Ionic React app is just a React app, we are free to utilize any of them in our apps!

In this post, I'll be going over one of my particular favorite libraries in the space, Styled Components, and show you how to get started using it to style your apps!

Meet Styled Components

Styled Components (SC for short from here on out) is a library that breaks down the barrier of tying styles to your React components. With SC, you don't need to declare particular CSS classes and hope they don't stomp on other classes in your project. Instead, you declare a component using the SC API, and then "attach" CSS to the component:

const MyButton = styled.button`
  padding: 12px;
  background-color: white;
  color: blue;
`;

If you are using VS Code, make sure to download the vscode-styled-components extension, which will give you syntax highlighting and CSS code completion when working with styled-components.

Those funky back-ticks above are a new(ish) JavaScript feature called Tagged Template Literals. You've used and loved normal template literals (Hello ${name}!) before. Tagged Template Literals are the same, but instead of doing the default string interpolation function when you use them on their own, you get to defined the function that gets ran on the string. Above, styled.button is a function that will take in the text in the literal and manipulate it into a React component with a class attached to it with our CSS. In the end, the MyButton component will emit HTML that will look similar to:

<button class="sc-bdnylx bIGghp">Click Me</button>

SC will worry about generating a unique class name on your behalf so your CSS is scoped to your component, and it won't affect other styles in your app.

Getting Started

Installing SC is a breeze. To get it into your Ionic React project run:

npm i styled-components @types/styled-components

This will install SC and it's typings so we can get great TypeScript autocompletion and type checking.

Next, import the styled object directly from styled-components:

import styled from 'styled-components';

And then start creating styled-components using the styled object. In the first example above, we created a button. However, the styled object has all the basic HTML primitive tags on it, like div, a, header, you name it. You can also extend other React components, as long as the component takes in className as a prop, and that className gets applied to the underlying HTML element the component renders.

Scoping CSS to an IonPage

One of the big benefits you get when using Ionic Angular is that the styles you define using the :host pseudo-selector in a component's CSS file are scoped only to that component. You can achieve the same thing in Ionic React using SC. Below, we will create a "styled" IonPage by passing in IonPage into the styled object:

const MyPage = styled(IonPage)`

`;

And replacing IonPage with MyPage in the JSX:

<MyPage>
  <IonHeader>...</IonHeader>
  <IonContent fullscreen>...</IonContent>
</MyPage>

Adding styles directly to IonPage isn't terribly useful, though. What it does buy us, however, is we can now target other classes in our page without fear that they will affect another page. Styled Components supports nesting CSS classes, a feature that I loved in SASS and find it hard to live without in plain CSS (though we might someday get native nesting support in CSS). So, we can start to define new elements with classes and target them in our MyPage component:

const MyPage = styled(IonPage)`
  .box {
    border: 1px solid white;
    margin: 10px;
    height: 200px;
    width: 200px;
  } 
`;

<MyPage>
  <IonHeader>...</IonHeader>
  <IonContent fullscreen>
      <div className="box"></div>
  </IonContent>
</MyPage>

Please forgive my lack of design powers, I rolled a 2 on Aesthetics when born.

Styling an Ionic Component

Styling one of the built-in Ionic components couldn't be easier. In fact, you already saw how to do so in the above example. Let's look at a component that offers some more options though, like IonButton:

const MyButton = styled(IonButton)`
  --background: green;
`;
...
// And to use it:
<MyButton>Hello!</MyButton>

Ionic components are web components that use Shadow DOM, therefore, styles defined outside of the web component don't affect the inner parts of the web component. To get around this, Ionic uses CSS Variables that allow developers to set styles that the web component can use.

In the above example, we set the background and border-color CSS variables, and these changes will only apply to our MyButton component.

Recently, Ionic also released support for Shadow Parts, which allows web component developers to expose certain parts of the web component and have those parts be targeted via CSS. Below, we accomplish the same thing as the example above but we target the native HTML button via the native shadow part:

const MyButton = styled(IonButton)`
  &::part(native) {
    background-color: green;
  }
`;

The & refers to the parent component itself, then we use the part pseudo-selector and target the native shadow part that the IonButton exposes.

Learn more about CSS Variables and Shadow Parts from our docs, and check out this post about Shadow Parts on the Ionic blog.

Wrapping up

CSS in React, (and Ionic React!), is a tricky subject, but fortunately, there are many ways you can go about it.

Hopefully, I gave you a taste of what you can do by using styled-components in an Ionic React app and opened your eyes to some of the possibilities.

I just covered the bare minimum of what you can do with styled-components, there's much more to it, and once you get the grasp of the library, you can create some pretty powerful components. I encourage you to visit the Styled Component docs to learn more and give it a try.

How are you going about styling your Ionic React apps? Is there something more you want to see? Hit me up in the comments below for reach out to me @elylucas and I just might write about it.

Happy Coding!

Testing Ionic React Apps with Jest and React Testing Library

Ely Lucas — Tue, 18 Feb 2020 16:42:33 +0000

It's 2020, and the testing frameworks for JavaScript applications have improved dramatically over the past few years.

Thanks to tools like Jest and React Testing Library, you can be testing your apps with a few lines of code.

Have you been looking into testing an Ionic React project, but not sure where to start? In this post, I'll go over the basics of how to get started as we build out an app using tests.

The Tools

First, let us go over a few of the tools that we will be using.

Jest is a testing framework built by the teams at Facebook (like React) and is very similar to other test frameworks like Jasmine and Mocha. Jest has been the defacto standard in React testing for quite awhile and is gaining popularity in other communities as well. What makes Jest great is it is easy to use, is flexible in the types of tests you want to create, and has a powerful test runner that is smart about running only tests for code that has changed.

Jest is already included and set up when you create a new Ionic React project, so getting started is super easy.

React Testing Library (RTL from here on out) is a relative newcomer to the React landscape, but it is also grown immensely in popularity. RTL lets you test React components without relying on the internal implementation details of the component. This approach mimics more of the way an actual user would use the app and promises to make tests more reliable and less brittle to change.

React Testing Library is now included when creating a new Ionic App and is our recommended test library.

The Ionic React Test Utils is a small suite of utilities that can help when testing Ionic React apps. It includes helpers to fire off custom Ionic events and mocks around some of our more complex components.

Getting Started

Our demo will keep a list of things we need to get done (don't call it a todo app!). Okay, it's a todo app, but a todo app is basic enough yet covers a few of the points I want to hit on testing Ionic components.

Start off creating a New Ionic React project via the Ionic CLI:

ionic start ionic-react-todos blank --type=react

If you are new to Ionic and need to get things set up, view our getting started guide here.

This command kicks off a new Ionic React project named "react-todos" using the blank template.

Next, we need to install Ionic React Test Utils, which we will use a bit later on. Go into the new directory and install the npm package:

cd ionic-react-todos
npm i @ionic/react-test-utils

Open up the project in your code editor. If you look in the src folder, you might notice that we already have a test file created for us in App.test.tsx. It is a simple test that just makes sure the main app component renders correctly without throwing an error.

it('renders without crashing', () => {
  const div = document.createElement('div');
  ReactDOM.render(<App />, div);
  ReactDOM.unmountComponentAtNode(div);
});

Go back into your command line, and fire up the Jest test runner:

npm run test

You might get a message saying there were no tests found, which is because Jest (by default) only runs tests on files that are modified since the last git commit. This is pretty handy and helps speed up testing by only running tests on files you are currently working on. Fortunately, we can see on the menu that we can change the "Watch Usage". Press "a" to run all tests.

Go ahead and leave Jest running. If we make any changes to our code, Jest automatically reruns the tests.

Your First Test

Okay, back in the code, let's create a test at src/pages/Home.test.tsx. We will create a basic test that makes sure the title of our page is "Ionic React Todos". Paste the following code into the test:

import React from 'react';
import { render } from '@testing-library/react';
import Home from './Home';

test('page should have a title of Ionic React Todos', async () => {
  const { findByText } = render(<Home />);
  await findByText('Ionic React Todos');
});

Let's break down the basic anatomy of a test. First, we have our imports, including the render method from RTL and then our Home component. Then we have our actual test. The test method is from Jest and is available globally, so there is no need to import it. For its first parameter, it takes in the name of the test, in which we usually provide some detailed text about what we are trying to accomplish, and then an anonymous function that contains the code for the test.

The render method takes our component and returns a bunch of helper methods to aid us in selecting pieces of the DOM that was rendered. The findByText method is one of them, and it looks for an element that contains the text passed into it. If it doesn't find one (or finds more than one), findByText throws an error. Therefore, there is no need for us to test the return value of findByText in this case.

For a list of all the helper methods render returns, check out the RTL docs here.

If you view Jest again you will see that the test failed:

We get a descriptive output about what happened and where. But basically, our text "Ionic React Todos" wasn't found. Update the <IonTitle> text in the Home component and come back, the tests should now pass:

Now that's what we like to see!

Building the Todo List

We have our first test passing, so that means it is time to write another failing one! When we have no todos to display, we want a message that says there are none. Here is the test for that:

test('when there are no todos, a no todos message should show', async () => {
  const { findByText } = render(<Home />);
  await findByText('No todos, add some!')
});

Take a look at the Jest runner, and you should see the new test failing. Let's update the component to display the message when there are no todos.

To get started, add a Todo interface to the top of Home and create a state variable using the useState hook to hold the todos. Also, update the <IonContent> to display a message if there are no todos.

Update Home to:

export interface Todo {
  id: number;
  text: string;
}

const Home: React.FC = () => {
  const [todos, setTodos] = useState<Todo[]>([]);
  return (
    <IonPage>
      <IonHeader>
        <IonToolbar>
          <IonTitle>Ionic React Todos</IonTitle>
        </IonToolbar>
      </IonHeader>
      <IonContent className="ion-padding">
        {todos.length === 0 ? (
          <div>No todos, add some!</div>
        ) : (
            <div>todos will go here</div>
          )}
      </IonContent>
    </IonPage>
  );
};

Our last test should now be passing. Let us write another to make sure our todos appear when there are some:

test('when TodoList is loaded with todos, then the todos should be in the list', async () => {
  const todos: Todo[] = [
    { id: 1, text: 'review PR' },
    { id: 2, text: 'update docs' }
  ];
  const { findByText } = render(<Home />);
  await findByText(todos[0].text);
  await findByText(todos[1].text);
});

We are running a couple of findByText calls here to make sure both the todos are added. If either of these fails to find an element, then an error is thrown.

Next, replace the <div>todos will go here</div> placeholder with this snippet which creates an IonList with an IonItem for each of the todos:

<IonList>
  {todos.map((todo, i) => (
    <IonItem key={i}>
      <IonLabel>
        <h2>{todo.text}</h2>
      </IonLabel>
      <IonIcon data-icon="trash" icon={trash} color="danger" slot="end" />
    </IonItem>
  ))}
</IonList>

All the Ionic components are imported from @ionic/react, and the trash icon is imported from ionicons/icons.

But wait, how's our Home component getting the array of Todos? Right now, it's not. Let's pretend the Home component calls into an API to fetch the todos. We won't have a real API, but we will create and load a json file with some data. Create a file at public/assets/todos.json and paste the following into it:

[
  {
    "id": 1, "text": "review PR"
  },
  {
    "id": 2, "text": "update readme"
  },
  {
    "id": 3, "text": "write docs"
  }
]

Back in Home, add a useEffect hook to call into the API and set the todos state:

useEffect(() => {
  async function doFetch() {
    const result = await fetch('/assets/todos.json');
    const data = await result.json();
    setTodos(data);
  }
  doFetch();
}, []);

Mocking an HTTP Request

Our tests start to fail because the fetch call won't be able to make the request while running in Jest. Fortunately, Jest allows us to mock fetch and return specific data. Add the following mockFetch method to the test file, which allows us to pass in some data that returns from the fetch call, as well as the beforeEach Jest helper, which calls the mock function before each test runs:

function mockFetch(data: any) {
  return jest.spyOn(window, 'fetch').mockResolvedValue(new Response(JSON.stringify(data)));
}

beforeEach(() => mockFetch([]));

In the last test, we can call mockFetch and pass in our todo array:

// todos array
mockFetch(todos);
// render and fetchByText methods

When the component calls fetch, it now returns the mock test data we have set up for it, and our test passes.

Adding a Todo

Next up is the bulk of our functionality, adding a todo to the list!

The next test does quite a bit. We will test clicking an add todo button, verifying the todo from loads, filling out the form, submitting the form, and lastly, making sure the todo appears in the list. This might seem like a lot, but RTL promotes testing a page, much like how a user would interact with it. This lets us cover quite a bit of functionality in a single test.

Go ahead and start to stub out the test with our first step: clicking a button to display the new todo form:

test('when clicking the new button, we should be able to add a new todo', async () => {
  const { findByTitle, findByText } = render(<Home />);
  const addButton = await findByTitle('Add Todo');  
  fireEvent.click(addButton);
});

fireEvent is imported from @testing-library/react and helps us simulate user interaction with the DOM elements that get returned. Here we are using it to click the addButton.

We are also using a new function returned from render here, findByTitle, which works very similarly to findByText, but instead looks for an element for a certain title. Update the Home component and add the following right above the closing </IonContent> tag:

<IonFab vertical="bottom" horizontal="end">
  <IonFabButton title="Add Todo" onClick={() => setShowModal(true)}>
    <IonIcon data-icon="add" icon={add} />
  </IonFabButton>
</IonFab>
<IonModal
  onDidDismiss={() => setShowModal(false)}
  isOpen={showModal}
>
  {/* Todo Form will go here */}
</IonModal>

Also add the state variable (right below the todos state) to maintain if we are displaying the modal containing the todo form:

const [showModal, setShowModal] = useState(false);

Buh uh oh, the tests have started to fail due to a new error:

This error leads us up to a bit of a tricky spot when it comes to testing Ionic React.

Using Ionic React Test Utils to mock Ionic Web Components

Note: Right before this blog was published, the JSDOM team announced customElement support for JSDOM. We are excited for this and will monitor if it fixes the issues we ran into and will update the post accordingly.

Ionic is written in web components, and Ionic React is a thin layer around those components to make them feel and behave more like the React components. Unfortunately, JSDOM does not currently support web components and errors if trying to access web component API, like customElements in the error above.

What we can do here, though, is use Jest to mock out the Ionic React components that can't render (like IonModal), which is where Ionic React Test Utils (IRTU) comes into play. IRTU provides a helper that can mock out all known Ionic components that have issues rendering in JSDOM. The mocked components simulate the actual ones by rendering minimal DOM to test.

To set it up, go into src/setupTests.ts file and update it with:

import { mockIonicReact } from '@ionic/react-test-utils';
mockIonicReact();

That should get the test passing.

For more info around this method, read Testing Web Components in React on Dev.to.

Testing the Form

Ok, let's continue flushing this test out. Now that the modal is loading, we will get the input box and save button:

const input = await findByTitle('Todo Text');
const button = await findByText('Save');

Time to implement the functionality for the form. Add the following form to the IonModal in Home, replacing {/* Todo Form will go here */}:

<IonToolbar>
  <IonTitle>Add Todo</IonTitle>
</IonToolbar>
<IonContent>
  <IonList>
    <IonItem>
      <IonLabel position="stacked">Todo</IonLabel>
      <IonInput id="todo" title="Todo Text" value={text} onIonChange={e => setText(e.detail.value!)} />
    </IonItem>
  </IonList>
  <IonButton expand="block" onClick={addTodo}>
    Save
  </IonButton>
</IonContent>

And add the new text/setText state variables as well as the method to save the todos to the top of the function:

const [text, setText] = useState('');

const addTodo = () => {
  const nextId = todos.reduce((id, todo) => Math.max(id, todo.id!), 0) + 1;
  const todo: Todo = {
    id: nextId,
    text
  };
  setTodos([...todos, todo]);
  setShowModal(false);
  setText('');
};

Next, we need to simulate filling out the form and clicking the save button. Typically, you would use the fireEvent.change method from RTU to simulate an input change. This fires the input element's change event. However, Ionic components fire custom 'ion' events like 'ionChange'. Therefore, we can't use fireEvent.change here.

To help with this, IRTU exports ionFireEvent, which wraps RTU's fireEvent, and augments it with all the custom Ionic events. Therefore, you can use ionFireEvent as a drop in replacement for fireEvent. To do so, import ionFireEvent and alias it to fireEvent:

import { ionFireEvent as fireEvent } from '@ionic/react-test-utils';

And remove the fireEvent import from @testing-library/react.

Now, we fire the ionChange event and click the button and verify that our todo gets added to the list:

fireEvent.ionChange(input, 'test todo');
fireEvent.click(button);
await findByText('test todo');

How did we do?

So far, we have written quite a bit of functionality driven entirely by tests. If we fire up the dev server:

ionic serve

We should see the list of todos get loaded from the fetch request, and be able to create a new todo.

You might notice there are delete icons for each of the todos. I'll leave that as an exercise for you to implement the delete functionality.

I've included a link to the full demo repository below that expands on the app a bit more, including deleting todos.

Wrapping up

It might have taken a bit of extra time to drive this development through tests, but now we have a good set of tests to run anytime we make updates to the app that gives us confidence that we didn't break anything.

Here is a list of resources for more info about the content covered in this post:

React Testing Library
Jest
Ionic React Test Utils
Kent C Dodd's Blog (author of React Testing Library and great articles on testing)
Github repo for the demo app

Interested in learning more about testing Ionic React apps? Let us know down below with your questions or comments.

Until next time, may your tests be green and your todos list complete!

Happy coding.

Testing Web Components in React?

Ely Lucas — Thu, 30 Jan 2020 22:33:50 +0000

Testing in React is a joy. Between Jest and React Testing Library (RTL from here on out), it is super simple to get up and running and productive. In fact, as of the CRA 3 release, RTL is included out of the box, making it even quicker.

However, there has been a sticky point that got me hung up lately, and that's been around testing a React component that consumes web components.

In this post, I'm going to cover the problem that arises with web components and testing, and show a particular method I used to get around it.

The Sticky Point

At Ionic, all of our UI components are written as web components via StencilJS. In Ionic React, we wrap those web components with lite React wrappers to help wire up the events and provide a better developer experience. Therefore, using an Ionic React component like:

<IonLabel>Hello</IonLabel>

Essentially becomes

<ion-label class="sc-ion-label-ios-h sc-ion-label-ios-s ios hydrated">Hello</ion-label>

By the time it is rendered in the browser.

There's quite a bit of logic in an Ionic component.

And <ion-label> is one of the simplest components we have.

I've been working on some testing guidance for Ionic React apps, and in doing so, I found that testing web components has its own set of challenges.

Now, this isn't a problem with Ionic, React, Jest, or RTL. The problem lies that the engine that Jest uses by default to render React components is JSDOM, which doesn't support web components at this time.

Therefore, when rendered, our <IonLabel> component example above, appears like this to RTL when JSDOM is done rendering it:

<ion-label>Hello</ion-label>

It is an empty HTML tag with no style, logic, or functionality. Not at all the same thing that gets rendered in the browser.

At first, I was determined to get these web components up and running so writing tests in RTL would match what gets rendered in a browser as closely as possible. I did have some requirements, however. I did not want to have to export the React app or have to do some overly complex configuration to get it running.

So, I tried a few different polyfills and some different Jest environments that support web components, but never quite got anything to work.

So, how are we supposed to test a React app that relies on web components if the web components don't render?

After thinking on it for a bit, however, I realized that maybe web components don't need to work to test your React app.

What is it you are trying to test?

When writing tests, you are often testing that some effect you induce to your component has some result. You load a page, and data appears. You click a button, and an XHR request gets sent off. An input gets changed, and updates a label elsewhere on the page, etc...

None of these have much to do with the internal workings of a web component.

When I have a list of items that I want to render into a <IonList>, I don't need to see all the divs, header tags, slots, and shadow dom created. All I want is to see the items I expect to appear in the list.

And, this is precisely what I get, even if the web components aren't working.

<IonList>
{people.map(p => <IonItem>{p.name}</IonItem)}
</IonList>

Renders:

<ion-list>
    <ion-item>Ely</ion-item>
    <ion-item>Joe</ion-item>
</ion-list>

I can use RTL to make sure all my peeps are in that list:

await waitForElement(() => people.map(p => getByText(p.name));

None of the test logic changes because my web component didn't render.

The empty, lifeless HTML tags that get rendered still respond to DOM events, too, so you can simulate a click on a <IonButton>. The buttons onClick event still triggers, and from our tests perspective, it doesn't matter if the event came from the HTML tag or the internal workings of IonButton.

What this comes down to is that we can think of a web component as an external piece of code, and the implementation details of that code shouldn't affect our app.

Testing components with Logic

But what if a web component has logic in it that we need to happen for our app to work? For instance, having a modal open when setting a prop, or having a toggle component fire an onChange event when clicked?

Not having logic work in Ionic components was a tricky sticky point for me and what caused me to search for so long on how to get web components to work with Jest and JSDOM.

After a bit though, I came to another realization: A web component can be thought of like an external service, and it might be possible to mock it as such.

If you are using web components in React, then the chances are good that you are using React wrappers around your web components to access the web components props and events (much like Ionic React wraps the core Ionic web components).

If you do use wrappers, then you can mock the React components you import via Jest's excellent mocking capabilities. If you don't and you use raw web components in your JSX, well, I'm not sure then. Maybe it's a good time to wrap them?

Let's say you have a toggle web component that fires a custom change event when clicked. Since the change event is raised internally in the component, it won't fire when running under JSDOM. Bummer! However, if we mock out that component, we can fire the event ourselves in the mock.

Here is an example of a web component, a React component the wraps the web one, the test, and the mock:

A web component defined somewhere in your app:

window.customElements.define('my-toggle', class extends HTMLElement {
  checked = false;
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    const toggle = document.createElement('input');
    toggle.setAttribute('type', 'checkbox');
    toggle.addEventListener('click', (e: MouseEvent) => {
      this.checked = !this.checked;
      this.dispatchEvent(new CustomEvent('myChange', {
        detail: {
          checked: this.checked
        }
      }));
    });
    shadow.appendChild(toggle);
  }
});

The React wrapper:

interface MyToggleProps {
  onMyChange?: (e: CustomEvent) => void
}

const MyToggle: React.FC<MyToggleProps> = ({ onMyChange }) => {
  const ref = useRef<HTMLElement>();

  useEffect(() => {
    onMyChange && ref.current!.addEventListener('myChange', (e) => onMyChange(e as any));
  }, []);

  return (
    <my-toggle ref={ref}></my-toggle>
  );
};

export default MyToggle;

And here how we could use the wrapper:

<MyToggle data-testid="my-toggle" onMyChange={(e) => setShowText(e.detail.checked)}></MyToggle>
{showText && <div>More text!</div>}

We will set up our test as follows:

test('when my toggle is clicked it should show more text', async () => {
  const {getByTestId, getByText } = render(<MyComponent />);
  const toggle = getByTestId('my-toggle');
  fireEvent.click(toggle);
  await waitForElement(() => getByText('More text!'))
});

However, when the test runs, the div element won't show up when the toggle is clicked. Why? Because the web component isn't actually running right now, and therefore the custom event firing in the click handler is not either.

So, I propose to mock the MyToggle React component with a slim implementation of the web component functionality.

To do so, add this mock somewhere in the setup of your tests:

function mockMyToggle({ onMyChange, ...rest }: any) {
  return (
    <my-toggle>
      <input {...rest} type="checkbox" onClick={(e) => {
        onMyChange && onMyChange(new CustomEvent('myChange', {
          detail: {
            checked: e.currentTarget.checked
          }
        }));
      }} />
    </my-toggle>
  );
}

jest.mock('../components/MyToggle', () => mockMyToggle);

The jest.mock method mocks out the entire MyToggle module at that specific path, which is where our component imports it from. More info.

In this mock, we have set up enough logic to simulate our web component without actually using it.

Now, when our test runs, it uses the mock instead of the real React component, and our test passes.

Thoughts?

The above is a lot to digest, but my premise is that if you are having issues trying to get web components to work in JSDOM, maybe you don't need to.

I haven't taken this idea too far yet, but so far, it has worked out decently. I'd love to hear your thoughts about the above approach or if you had success with other methods.

And, who knows, maybe JSDOM will land web component support, and this will all be moot.

Announcing Ionic React Hooks

Ely Lucas — Tue, 03 Dec 2019 17:06:50 +0000

Last month we announced Ionic React, and have been blown away by the reception from both the Ionic community as well as the React community. Today, we are excited to launch a companion project to Ionic React that makes tying into device hardware and APIs a breeze in an Ionic React project.

You may have heard of Capacitor, our native app management layer that lets you leverage APIs that work across iOS, Android, Electron, and the web, all with one code base and JS. You can use Capacitor to access various device features, such as the camera, GPS, network status, and more. The SDK for Capacitor is vanilla JavaScript, which any web framework can use. However, we wanted to take the experience of accessing Capacitor APIs to the next level by making them feel like a natural extension to the React experience.

So today, we are launching Ionic React Hooks, a collection of React hooks that act as wrappers around the Capacitor APIs, as well as some other Ionic platform-specific features. With Ionic React Hooks, you can start accessing device hardware in just a few lines of code, all while coding in a familiar React paradigm.

What's the Hook for Hooks?

Hooks were introduced in React v16.8 and allow a way to access certain React features in a simple and clean manner while using functional components.

Before hooks, you pretty much needed to use class-based components to have local state, make web API calls, use React's context, or tie into a component's lifecycle events. While class-based components are great, developers often prefer to use the functional approach, which consists of a simple function that takes in a props object and returns a React element. Functional components are often smaller and easier to understand than their class-based counterparts.

Hooks make it possible to do more complex tasks in a functional component.

For more information about React Hooks and a primer on how they work, head over to React's guide to hooks here.

At Ionic, we are fans of functional components and hooks, so it was natural to want a way to consume the APIs we build using a hooks based approach. And that's where Ionic React Hooks comes in! Let's see how to get started.

A Quick Example

Hooks are great because they abstract away the messy details of accessing Capacitor APIs and setting/clearing listeners. For example, to track Geolocation position in realtime, we just need to call one hook in our component:

import { useWatchPosition } from '@ionic/react-hooks/geolocation';

const { currentPosition, startWatch, clearWatch } = useWatchPosition();

And currentPosition will be available in our component to access. The return type of the hook follows the Geolocation API in Capacitor, but all the events and handlers are managed for you!

Adding Ionic React Hooks to an existing Ionic React Project

For those using Ionic React today, adding Ionic React Hooks to your project is simple. First, enable Capacitor in your project:

ionic integrations enable capacitor

Next, install Ionic React Hooks and PWA Elements.

npm i @ionic/pwa-elements @ionic/react-hooks

Ionic React Hooks Tutorial

Let's build a simple camera app that takes a picture and displays it on the user’s device. The best part? It will run on the web or as a native mobile app - with no code changes - thanks to Capacitor.

First, let's kick off a new Ionic React application through the CLI:

ionic start my-react-app blank --type react

If you are new to Ionic or need to get the CLI installed, visit here for info on how to get started with the Ionic CLI.

Next, enable Capacitor in the project by running:

ionic integrations enable capacitor

This will prepare the project by installing the necessary Capacitor dependencies and setting up some configuration for us.

Now install the Ionic PWA Elements and Ionic React Hooks packages:

npm i @ionic/pwa-elements @ionic/react-hooks

PWA elements is a set of https://stenciljs.com/ web components that display UI elements when not running natively on a device. These elements are lazy-loaded as needed, so including them will not increase your initial bundle size. In our demo app, the camera interface displayed is from PWA Elements.

Note: PWA Elements is optional, the hooks will work without it but provide a simpler UI experience on the web.

Now that we have the project created and all our dependencies set up, open the project in your favorite code editor.

In index.tsx, we need to register the PWA Elements library. Update the file to import defineCustomElements and call that method at the bottom:

import { defineCustomElements } from '@ionic/pwa-elements/loader';

ReactDOM.render(<App />, document.getElementById('root'));

defineCustomElements(window);

Next, open up Home.tsx, and add the following code right below the imports:

import { useCamera, availableFeatures } from '@ionic/react-hooks/camera';

You import each of the hooks for a specific Capacitor plugin by importing them from their specific path.

Each of the plugins also has an availableFeatures object. While Capacitor allows you to write to one API across several platforms, not all features are supported on all platforms. It is recommended to check if the feature you intend to use is available before using it to avoid any runtime errors.

Inside the functional component, add the following code:

const { photo, getPhoto} = useCamera();

const handleTakePhoto = () => {
    if(availableFeatures.getPhoto) {
      getPhoto({
        quality: 100,
        allowEditing: false,
        resultType: CameraResultType.DataUrl
      })
    }
}

CameraResultType is imported from "@capacitor/core"

From the useCamera hook, we get back two values. The first is the photo value, a CameraPhoto object which contains meta-data around the result of the method call. It will be undefined at first. However, it will be updated with the result of getPhoto when that method is called (similar to how the state variable from useState works). The getPhoto method, when invoked, will launch the camera plugin to take a photo.

The handleTakePhoto method will be invoked from a button click later, but here we are simply checking if the platform the app is currently running on can get a photo, and then calling into the getPhoto method with some options.

Next, replace the content of IonContent with:

{availableFeatures.getPhoto ? (
  <div>
    <div><IonButton onClick={handleTakePhoto}>Take Photo</IonButton></div>
    <div>{photo && <img alt="" src={photo.dataUrl} />}</div>
  </div>
) : <div>Camera not available on this platform</div>}

Here, we check if the feature is once again available (so we don't show a button that can’t be used), and if so, display the UI to take the picture and view the photo.

In the options we send to getPhoto, we specify dataUrl as the result type. This type gives us back a base64 encoded string of the photo that can be directly set as the image's src attribute.

With all that in place, we can now run ionic serve, and from within the web browser, take a photo and display it!

For more info about how to use the Capacitor Camera API, go to the docs here.

Running on a Native iOS App

We currently have our app running on one platform - the web - which could be deployed as a PWA and function as is. Now, let's take this app and make a native iOS app and have it run on an iPhone as well.

First, we need to build our app:

npm run build

This creates a production build of our React app in the build folder.

Next, add the iOS platform via the Capacitor CLI. This command will create an iOS project for us and copy our build folder into the native project:

npx cap add ios

If this is your first time creating a native Capacitor app, you might need to install some additional software. Visit our getting started guide for more info.

Once finished, open up the iOS app in Xcode:

npx cap open ios

Now, you can build your app and run it on an actual device!

For more info on the development workflow in Capacitor, view this doc.

Notice that when the button is clicked, you get presented with a native iOS UI to either choose a photo from an album or use the camera to take a new photo. Capacitor is automatically detecting you are on an actual device and using that device's capability to offer a better, more natural experience for the user.

What's Next for Ionic React Hooks?

This first release of Ionic React Hooks is very much a beta release, with only a few of the Capacitor APIs covered so far.

We are releasing this project as a community-based project and would love to get your feedback and have you help contribute to its future.

To contribute, head over to the GitHub Repo, file an issue with your idea and then submit a PR.

Ideas on what to contribute could be bug fixes, new hooks for Capacitor APIs, documentation updates to the readme, or new hooks that would benefit Ionic React developers in general.

Wrapping up

Ionic React Hooks aims to make accessing device hardware in Ionic React projects using Capacitor as straightforward as possible for React developers. In the process, they make it easier than using Capacitor by itself or through another framework!

Here are a few resources to get you up and running:

Thank you for your time today, and we hope you check it out and let us know how it goes.

Happy Coding!

Adding Ionic React to an existing React project

Ely Lucas — Wed, 16 Oct 2019 19:42:32 +0000

Earlier this week, we launched Ionic React (read the announcement here). To get started with a new Ionic React project is quite easy, but what if you have an existing React project and want to integrate Ionic into it?

Fortunately the process it pretty easy. In this short guide, I'll go through how to start using Ionic React in an existing project. I'll start with how to use individual components, and then touch on how to get the full Ionic app experience.

Using Individual Ionic Components

Ionic React has around 100 components that you can begin using in your app immediately to help make it more mobile-friendly.

To get started with just using components, add the @ionic/react package to your project:

npm i @ionic/react

Next, import the core CSS for Ionic somewhere in your main app file:

import '@ionic/react/css/core.css';

Now, you can import any of the components and begin to use them right away. Here we are importing the IonButton and IonDatetme components and using them anywhere in our app:

import { IonButton, IonDatetime } from '@ionic/react';

<IonDatetime displayFormat="MM/DD/YYYY" placeholder="Select Date"></IonDatetime>
<IonButton fill="clear">Start</IonButton>

Using Ionic Pages

If you want to convert part of your app and give it the whole Ionic experience, there are a few additional steps to take to get this setup.

First, import some additional CSS files that help set up the overall structure of the page and some utility helpers:

/* Basic CSS for apps built with Ionic */
import '@ionic/react/css/normalize.css';
import '@ionic/react/css/structure.css';
import '@ionic/react/css/typography.css';

/* Optional CSS utils that can be commented out */
import '@ionic/react/css/padding.css';
import '@ionic/react/css/float-elements.css';
import '@ionic/react/css/text-alignment.css';
import '@ionic/react/css/text-transformation.css';
import '@ionic/react/css/flex-utils.css';
import '@ionic/react/css/display.css';

If you are using another CSS framework (like Bootstrap), you might want to isolate the Ionic pages away from them. This will help to ensure there aren't any CSS conflicts between the libraries.

Next, install the @ionic/react-router library:

npm i @ionic/react-router

The Ionic React Router library is a small wrapper around the popular React Router library and helps provide the functionality we need for native-like page transitions.

The main Ionic page will need a couple of base components. First, use a IonApp component (from @ionic/react) as the root component, and then use IonReactRouter (from @ionic/react-router).

IonApp sets up our main container, with the necessary styling needed for our structural components. IonReactRouter is a small wrapper for React Routers BrowserRouter and should be used in its place.

Then, wrap all your routes in an IonRouterOutlet, which is what manages our Ionic pages.

<IonApp>
  <IonReactRouter>
    <IonRouterOutlet>
      <Route path="/" exact component={Home} />
      <Route path="/about" exact component={About} />
    </IonRouterOutlet>
  </IonReactRouter>
</IonApp>

Now you can setup Ionic pages like so:

<IonPage>
  <IonHeader>
    <IonToolbar>
      <IonTitle>My Page</IonTitle>
    </IonToolbar>
  </IonHeader>
  <IonContent>
    <IonDatetime displayFormat="MM/DD/YYYY" placeholder="Select Date"></IonDatetime>
    <IonButton fill="clear">Start</IonButton>
  </IonContent>
</IonPage>

Note that having IonPage is important to have as the base component for your "Ionic" pages. IonPage is the element we look for to do the page transition on.

For more information on routing and navigation in Ionic React, see here.

Customize the Theme

To customize the look and feel of the components, we have some CSS variables you can override to provide a theme for your components. Set these somewhere in your main CSS file:

:root {
  --ion-color-angular: #ac282b;
  --ion-color-communication: #8e8d93;
  --ion-color-tooling: #fe4c52;
  --ion-color-services: #fd8b2d;
  --ion-color-design: #fed035;
  --ion-color-workshop: #69bb7b;
  --ion-color-food: #3bc7c4;
  --ion-color-documentation: #b16be3;
  --ion-color-navigation: #6600cc;

  --ion-color-primary: #3880ff;
  --ion-color-primary-rgb: 56, 128, 255;
  --ion-color-primary-contrast: #ffffff;
  --ion-color-primary-contrast-rgb: 255, 255, 255;
  --ion-color-primary-shade: #3171e0;
  --ion-color-primary-tint: #4c8dff;

  --ion-color-secondary: #0cd1e8;
  --ion-color-secondary-rgb: 12, 209, 232;
  --ion-color-secondary-contrast: #ffffff;
  --ion-color-secondary-contrast-rgb: 255, 255, 255;
  --ion-color-secondary-shade: #0bb8cc;
  --ion-color-secondary-tint: #24d6ea;

  --ion-color-tertiary: #7044ff;
  --ion-color-tertiary-rgb: 112, 68, 255;
  --ion-color-tertiary-contrast: #ffffff;
  --ion-color-tertiary-contrast-rgb: 255, 255, 255;
  --ion-color-tertiary-shade: #633ce0;
  --ion-color-tertiary-tint: #7e57ff;

  --ion-color-success: #10dc60;
  --ion-color-success-rgb: 16, 220, 96;
  --ion-color-success-contrast: #ffffff;
  --ion-color-success-contrast-rgb: 255, 255, 255;
  --ion-color-success-shade: #0ec254;
  --ion-color-success-tint: #28e070;

  --ion-color-warning: #ffce00;
  --ion-color-warning-rgb: 255, 206, 0;
  --ion-color-warning-contrast: #ffffff;
  --ion-color-warning-contrast-rgb: 255, 255, 255;
  --ion-color-warning-shade: #e0b500;
  --ion-color-warning-tint: #ffd31a;

  --ion-color-danger: #f04141;
  --ion-color-danger-rgb: 245, 61, 61;
  --ion-color-danger-contrast: #ffffff;
  --ion-color-danger-contrast-rgb: 255, 255, 255;
  --ion-color-danger-shade: #d33939;
  --ion-color-danger-tint: #f25454;

  --ion-color-dark: #222428;
  --ion-color-dark-rgb: 34, 34, 34;
  --ion-color-dark-contrast: #ffffff;
  --ion-color-dark-contrast-rgb: 255, 255, 255;
  --ion-color-dark-shade: #1e2023;
  --ion-color-dark-tint: #383a3e;

  --ion-color-medium: #989aa2;
  --ion-color-medium-rgb: 152, 154, 162;
  --ion-color-medium-contrast: #ffffff;
  --ion-color-medium-contrast-rgb: 255, 255, 255;
  --ion-color-medium-shade: #86888f;
  --ion-color-medium-tint: #a2a4ab;

  --ion-color-light: #f4f5f8;
  --ion-color-light-rgb: 244, 244, 244;
  --ion-color-light-contrast: #000000;
  --ion-color-light-contrast-rgb: 0, 0, 0;
  --ion-color-light-shade: #d7d8da;
  --ion-color-light-tint: #f5f6f9;
}

For more info on theming your Ionic app, see the guide here.

Wrapping up

Adding Ionic React to an existing React project is fairly simple and can be done in just a few minutes.

The great thing about using individual components from Ionic React is that you only import the component you need. Each component is lazy loaded at runtime so that it won't bloat your bundle size. This makes Ionic React ideal for adding it to existing projects that need to look and work great on mobile devices.

Announcing the Ionic React Release Candidate!

Ely Lucas — Wed, 14 Aug 2019 14:40:24 +0000

Today we are excited to announce that the Release Candidate for Ionic React has launched and is now available!

We released the first Beta of Ionic React in February, and since then, we have received a ton of feedback and contributions from the community. Based on this feedback, we have been working to make Ionic React a great experience not only for React developers but for anyone looking to jump into web development.

Ionic React RC marks the first major release of our vision to bring Ionic development to more developers on other frameworks. This was made possible by Ionic v4.0, which was completely re-written from the ground up focusing on web standards and not dependent on a particular framework. Ionic v4.0 makes it possible for us to target many frameworks while still having our core components be a single code base shared across all these frameworks.

Why Ionic React?

If you can use Ionic with any framework, why are there specialized packages like @ionic/react? This is a good and fair question.

While you could import the core Ionic components directly into your React project, the developer experience is not where we think it should be when working with Ionic. While working with web components is possible in React, there is some boilerplate code you would have to write to properly communicate with the web components.

Ionic React is a thin wrapper around our core components, exporting them as native React components and handling this boilerplate code for you. Thus using @ionic/react feels natural when working in React, and offers many React paradigms that aren't there in the core components.

There are also a few features that were still required to be written in the native framework, such as page lifetime management and lifecycle methods. To accomplish this, we extend the popular react-router package with @ionic/react-router. It is important to note that we are not creating a new router, but just extending React Router to provide a better experience when working with Ionic apps.

Getting Started

If you haven't already done so, grab the latest v5 release of the Ionic CLI:

npm i ionic -g

And create an Ionic React project by specifying the type of "react":

ionic start MyReactApp --type=react

You will see that all of our standard starter templates are there, choose your favorite (I'll choose tabs).

The Ionic CLI will create your project for you and install dependencies. Under the hood, the CLI uses Create React App (CRA) to initialize the React bits of the project. If you are familiar with CRA then all the functionality provided by the CRA scripts are available to you in Ionic React.

Next, go into the new folder (MyReactApp), and run ionic serve. Your app will be compiled and launched into a new browser window:

For a more in-depth getting started tutorial, check out our Build your First App guide for Ionic React in the docs.

Whats Next?

Now that Ionic React RC is out, we want you to test it out and send us your feedback. To report an issue or comment, head over to the GitHub repo and tag the issue with "package react". You can also head over to the forums to ask questions or start a discussion.

For the Ionic Team, our focus is set on releasing Ionic React final "soon". We will be looking closely at any issues that pop up during the RC phase and working on some final code stabilization and minor bug fixes. We don't expect any of the APIs to have any more significant changes.

We also plan on creating some more content and guides in the docs to help with some best practices we've found when working with Ionic React.

Until then, keep sending us your feedback and happy coding!

P.S. If you are heading out to React Rally on August 22nd - 23rd, stop by our booth and say Hi! Several members of the core team will be out there and we would love to chat! We might even have something new to talk about then...

Resources linked above in one convenient little place:

Build Your First Ionic React App
Ionic React Project on Github
Ionic Forums
Create React App

DEV Community: Ely Lucas

Introducing ts-dash: A Quick and Simple TypeScript Project Creator

The Itch

create-ts-dash

What You Get

Need a Web Server?

Optional Tooling

"Doesn't This Already Exist?"

Try It Out

Introducing the New Overlay Hooks for Ionic React

Overlay Components

Overlay Hooks

More Info

How to Reduce the Number of Renders in an Ionic React App

Project Setup

Why you render so much?

Optimizing the renders

Component Memoization

Route Setup

Wrapping Up

How to Confirm Leaving a Page in Ionic React with React Router

Using React Router's Prompt Component

Customizing the Confirm UI

Using the Browsers beforeUnload Event

Wrapping up

How to CSS in Ionic React with Styled Components

Meet Styled Components

Getting Started

Scoping CSS to an IonPage

Styling an Ionic Component

Wrapping up

Testing Ionic React Apps with Jest and React Testing Library

The Tools

Getting Started

Your First Test

Building the Todo List

Mocking an HTTP Request

Adding a Todo

Using Ionic React Test Utils to mock Ionic Web Components

Testing the Form

How did we do?

Wrapping up

Testing Web Components in React?

The Sticky Point

What is it you are trying to test?

Testing components with Logic

Thoughts?

Announcing Ionic React Hooks

What's the Hook for Hooks?

A Quick Example

Adding Ionic React Hooks to an existing Ionic React Project

Ionic React Hooks Tutorial

Running on a Native iOS App

What's Next for Ionic React Hooks?

Wrapping up

Adding Ionic React to an existing React project

Using Individual Ionic Components

Using Ionic Pages

Customize the Theme

Wrapping up

Announcing the Ionic React Release Candidate!

Why Ionic React?

Getting Started

Whats Next?

Using the Browsers `beforeUnload` Event