Complete demo code available at: https://github.com/LastCallMedia/mercure-api-platform-demo
In this final video of our series about Mercure, we give an overview of a prebuilt, simple react app. We show two browsers side-by-side. One posts to our API Platform app which is configured to publish to Mercure. The other browser receives the update through its Mercure subscription. After that we talk about some additional projects and useful docs (links below).
Relevant URLs:
https://github.com/api-platform/client-generator
https://developer.mozilla.org/en-US/docs/Web/API/EventSource
https://github.com/Yaffle/EventSource/
https://github.com/dunglas/mercure
https://github.com/api-platform/api-platform
Transcript:
[bright electronic music]
Silas: Welcome back, this is the last video in our series on Mercure. In the previous video, we showed a sample API Platform project connecting to Mercure and sending updates, and we showed the Mercure demo website receiving those updates. In this video, we’re just going to quickly review a sample React project that I’ve made to show all of this working in something that is a little bit more like something you might see on the internet. Something a little more useful.
So, here I’ve replaced the API Platform client folder with my own code, and it’s just a simple React app. Inside .env we have REACT_API_ENTRYPOINT pointing at API Platform, and we have REACT_APP_MERCURE_HUB_URL pointing at our Mercure hub. Inside of source we have index, which just loads App. App has h1 Greetings, and some nice text, and has the AddGreeting component, which is a form which does a post to API Platform to create a greeting just like we did in the last video through the the API Platform user interface. Below that we have GreetingList, which first gets all of the greetings from API Platform, and then it connects to Mercure to listen to updates and it shows any new greetings that are posted.
AddGreeting—let’s just change this quickly to AddGreeting. And copy and paste issue. AddGreeting here has the form, which calls, handles, submit. This calls and makes an axios post. Axios is just a helper library to help you make posts and GETs and other requests to a server. And here it’s calling API Platform/greetings. And it’s passing in the object with name and the value. So this is exactly what we were doing in the previous video, except now we’re just doing it more dynamically, and passing it in from the value of a text field.
GreetingList is the other component, which on mount it has a state variable with greetings array, and on mount it calls and axios get to API Platform. It gets the response, and then it sets the state of greetings to all of the greetings that are returned in that response. And then after that, it loads up the Mercure URL right here into a URL instance. And then, it sets topic of that like we did it in the previous video. It sets it to the API Platform URL/greetings, and then this ID placeholder at the end.
It creates an instance with that URL. It creates an EventSource instance. And this is how we’re going to connect to the server and listen to updates. And just so you know, if you’re targeting IE compatibility, you will need a polyfill for this, but otherwise it has good compatibility and it should work in any browser you need. After that, it sets up the listener for messages, and when a new message comes in, it calls updateGreetings. And updateGreetings just takes the data from the update, appends it to our array of greetings. Then in render, these greetings are looped through, and it creates a div with each greeting name inside of it. And then it shows those on the page. So, pretty simple. If you’re unfamiliar with React, this may look a little bit daunting, I guess, but hopefully that description helps clear things up a little bit.
So, if we open our browser here, we have two of these side-by-side, and the idea is that if I submit the form here, it will show the text on the other one instantly. And in the end that’s the goal of everything we’ve been doing. So, just say hello, and click submit, and it showed up pretty much instantly on the other one. So, we know everything’s working.
Okay, wrapping up. I just wanted to make a couple final points. One is that API Platform has a project called the “client generator,” which can be used to give you a foundation for either a React app, or a Vue.js app. And this is if you don’t wanna start custom like I was doing with my demo app, you can look at this. It’ll give you a base, some base code connecting to your API Platform API’s. And they’ve recently added in Mercure support for this. So, I haven’t used this too much, but I think it’s definitely worth checking out.
Next is that you probably noticed that we weren’t using JWT tokens at all in our client application. However, we talked a lot about those tokens in the previous videos, so I just wanted to point out that this is because we had the “allow anonymous” environment variable turned to one in our docker compose. So that’s why it worked. For my project I will be removing that environment variable, because I want to ensure that only people with JWT tokens can connect to Mercure and get updates. So I’m going to lock it down. And I imagine that there are many projects which would have similar requirements. So, I just wanted to point out that there are two ways your client application can send the token. One is you can use the Mercure authorization cookie, and if you do that, you just need to send the cookie. And you need to make sure that that’s being sent when you set up your EventSource object. You may have CORS issues when doing this, so I would just recommend to look at the EventSource documentation. And in the configuration argument there is a flag to set with credentials to true, so that those cookies will get passed.
The other option is to set the authorization HTTP Header, and this is a pretty standard way to send the tokens to servers. So, one issue with this is that the standard EventSource doesn’t allow you to set HTTP headers. So you may need to look at using a polyfill such as this one, which you can find on GitHub. And if you scroll down this page, you’ll see that it allows setting customer headers, and it has sample code for doing that. You’d replace X-Custom-Header with the word “authorization,” and you’d change value to the word “bearer,” space, and then your token, which is the standard way of sending tokens to servers.
Lastly, I’ve uploaded the code here on GitHub, so feel free to check it out. Read through the code if you want, write any issues, submit pull requests. If you have any improvements, I’d be very excited about that. Let me know, and with that I will say goodbye. Thank you very much for your time. I hope that you are excited about Mercure, because I think it’s a great project, and I’m excited to see where it goes. Thank you, bye.
[bright electronic music]
