Build Your First React App

Transcript

Hello everyone and thank you for watching this live or if you’re going to watch the recording thank you as well. Welcome to this beginner session that we named build your first react app with am headless and I said beginner session because it’s targeted to any developer including the ones that just started their journey as a developer. My name is Stéphane Rengel, I’m a software engineer working for Adobe AM sites. Over almost the last decade I was involved in building user experiences and improving the developer experience for for AM and contributed mostly to AM’s UI, App Builder and developer website. So we prepared this session to give you an introduction of AM headless and its core principles, namely content fragments and its GraphQL API. At the end of this session I’m going to show you how you can easily set up a dev environment that retrieves content from AM headless in a react app without AM. Let’s start with GraphQL. That’s the introduction. Let’s first have a look at the definition of GraphQL given by graphql.org. It’s a query language API where the client can request the data they need over HTTP and this is possible because of the GraphQL type system used to define the data and queries that can be made by clients. Historically it was built by Facebook in 2012 and went public three years later. Now it’s home in a non-profit foundation called GraphQL Foundation. My point here is GraphQL is not a new technology. It’s a pretty solid technology now that has made its way across web platforms and it’s baked by a strong non-profit community. So question, if you look at the typical web server client architecture in theory where’s the GraphQL layer? It’s between the client and the server because the GraphQL layer is the contract between both server and client so they understand each other. The GraphQL layer is the same as the client and server can be written in different languages but thanks to GraphQL the client can request the server any data at once and the server will respond with exactly that data. If you remember the definition I mentioned a typing system. Now the typing system in GraphQL is really the backbone. On the left side you can see the definition of a developer query that returns a person and on the right side you can see the definition of a person with three fields the id typed as id and name and email. GraphQL has built-in default types called scholar types which are string, boolean, float, int and id. If you want to define a field that cannot be null you can simply add an exclamation point. So in this case here you’re making sure the person always has an id. The definition of types and queries is defined in the GraphQL schema which is the main contract between client and server. Here we are executing the developer query but we only want the name so in this case it returns a JSON object with the name JSON being a common format to represent structured content for the web. For executing the response the GraphQL API will validate the client query and then resolve the query. Each requested field is then resolved to return the right value. Of course you can use variables like here in your queries to only request for example a developer name based on the id. You can name queries as well like here developer name and pass the id variable. It’s of type id and can be null. You can of course do a lot more like filtering, sorting and pagination and here I only scratched the surface of GraphQL. There’s a lot more to it and I recommend if you just started with GraphQL go to graphql.org slash learn where you can learn more about things like mutations, meta fields and introspection and so on. So I quickly talked about GraphQL. Let’s continue with AEM Headless which is based on GraphQL and one of the key concepts are content fragments. Content fragments are reusable structured data elements which is different from unstructured data elements like text files where the data is altered without rules or constraints. The other key concept is content fragment models which are used to define the structure of content fragments. This is the typing system to define structured content for GraphQL. And finally the last element is the user interface to find and edit your content fragment models and the related content fragments. I’m not going to deep dive here, there are other sessions coming up next where we’ll show you the new headless features, the new UI and how to extend the UI. Once the content fragments are defined you can naturally query the content via a GraphQL API endpoint. Common queries type include listing content fragments or querying a single content fragment based on its path field which represents its location in the AEM content repository. So if you’re familiar with GraphQL you’ll naturally be familiar with AEM Headless. Okay I’m going to talk a bit about React before the demo since we picked React to build the UI up to demo. And as always let’s first have a look at the definition given by React. So React is a JavaScript library for building user interfaces. It’s open source, it’s free, it’s easy to use, it’s easy to use. It was founded by Facebook in 2013. So Facebook founded React right after GraphQL. Coincidence I don’t know but I can say they both work very well together. I highlighted the word library because there’s a difference between a framework like Angular and a library like React. When you build an app with a library you are free to complement the library with other parts of the ecosystem to build your own custom framework. For example there are different routing systems, different data fetching systems and so on and React doesn’t tell you how to do that. It only cares about rendering the UI at all. It’s up to you to define these parts of your app. While if you use a framework in most cases the framework will dictate how these things work. This doesn’t leave much room for customization unless the framework allows it. So what makes React so popular? The templating language to write the UI is JSX which stands for JavaScript syntax extension. It looks a lot like HTML. If you’re writing JSX code the browser doesn’t understand it by default. You’ll need a compiler like bubble to compile it to JavaScript. Learn once write anywhere. What does it mean? It means React is not only used to build client-side web UIs you can also use its third side or even to build mobile apps. React is a very important tool in React native. As I said before because it’s just an UI library you might need a routing system, styling system and so on to make your life as a developer easier and to be more productive. This is why there’s a huge ecosystem around React mostly open source and free built by the developer community. Here’s an example of a simple React component called my button. When clicked we’ll increment an internal counter and display the current counter value. As you can see the component is just a JavaScript function. Let’s start from the top. First we import a state hook from React which will help us to define the counter state. React hooks help us to build components like state but you can build your own reusable hooks for example for data fetching. We initialize the counter state to zero and it’s stored in the count variable and we get additional count function to update the counter. Then we define a click handler function that increments the counter value by one and finally we return the button that we attached the click event listener to and text with the counter variable. So the last bullet point here I added, dome mutation optimization. dome stands for document object model which is the resulting object of the browser processing the HTML. React will automatically and precisely update parts of the dome thanks to its inner virtual dome. It is synced with the actual browser so it makes dome render updates more efficient. Looking at the future of React there’s a lot of energy and momentum around React server components which will likely help to reduce client-side JavaScripts and similar to the previous example components are still functions, JavaScript functions, but they can be asynchronous so that components can fetch the data server-side to avoid an unnecessary client-server round trip. So here for example we are rendering a list of articles types and descriptions from the server directly. This server component example is taken from the latest version of the framework Next.js which is a React backend framework. It’s probably the most popular one right now and if you are interested in how to couple AM headless with Next.js and how to make your components editable in AM then you’re lucky because we have also a session coming up next that will show you how to do that. Of course there are other frameworks that work with React, not only Next. I listed a few of them here so Remix is very similar to Next.js but still different. Astro and Gatsby are mostly known as static site generators and yeah there are a lot more. Okay now enough talking let’s switch to the code. So I’ve built this demo which is a sandbox so that any developer without AM access can jump right into a ready-to-go dev environment powering a typical client-side React app that renders content from AM. And for that all you need is an internet connection, a browser, and less than a minute. And here’s the link to the repository GitHub. It’s public, open source. Let’s check it out. So I called it AM weekend headless React sandbox because what it does is it takes the weekend site, content fragments, and it makes them credible via the AM headless SDK locally. The weekend site is AM’s reference app. It’s public and so is its GraphQL endpoint for adventures. The sandbox app is bootstrapped from Veeam which is a next generation front-end tool to build and run your app. Veeam is actually the French word for fast and yes it’s true it’s very fast especially the dev environment. So let’s see how the sandbox app looks like and yeah let’s hit the blue button to open the dev environment. Can we get it working under a minute? Let’s see. So it’s installing the dependencies first. Let’s have a look at the dependencies. We’ve got of course React, the AM headless SDK, and React query as dependency. React query provides nice custom hooks to make data fetching a lot easier and we’ve got a bunch of other dev dependencies that powers our dev environment like GraphQL dependencies, Express server for the local GraphQL server, and Veeam for our React app. So there we go. The GraphQL server is up and reads as well and we’ve got on the right side a preview. We’ve got a list of adventures listed here, image, title, and description. So if you have to remember one thing about this session this is it. There is a dev environment that you have with the AM headless content in your browser under a minute. As I said the content is pulled from weaken site into a local AM folder here. And maybe the first thing you see is the GraphQL schema. That’s how it works. There’s a lot here. So this schema, this is actually the schema AM will generate out of your content fragment models. Here we have an adventure model with several fields like title, description, and so on. But we also have the actual content fragment values stored as JSON here. Values-urbcamp, that’s the title of the first adventure. And a lot of data. Also I wanted to show images. While we… … So we also pull the assets corresponding to this reference. So we just recreate the same path under assets and pull the images in this case. So for the first adventure it’s this one. And all that information powers the local GraphQL server which is running on port 3000. We can have a look at the GraphQL server code. So here I’m loading the schema and defining the resolver functions for the list and by path pairs after loading all the content fragments from the local file. I am also mocking fields that are that have no value, Scala fits, which can be useful in a dev environment as I’ll show you next. And finally I’m also enabling GraphQL which is a UI to exit your queries and we can open it in a new tab. Okay that’s the React app and let’s move to GraphQL. This is all local running in your browser. Let’s execute a simple query to retrieve all adventure titles. Adventure lists, items, adventure title. There you go. You can also click yourself through the different models using the docs here. So here for example adventure lists returns an adventure model results and a bunch of items which are adventure models and there you got two different fields of an adventure model. Let’s execute another query to retrieve a single adventure by path provided as a variable. And I’ve got the example in the readme. Let’s just copy it. So here I have the path, it’s passed down to the adventure by path query and I just need to copy paste the variable as well which is the path of the first. There you go. Now because this is local you can actually very easily edit the schema and the content if you want to. So let’s say I’d like to add a new field to the adventure model. I’ll go to the schema and add it just there. Let’s call it adventure subtitle. And let’s look it’s here adventure subtitle. And you can see that the value I get is actually the mocked value. Because we’re mocking results that have no value. So we gotta run them string again. But we could also just add a real value if we add it to the adventure list in the JSON file. Let’s go to the adventure list and add a real value for the first adventure for adventure subtitle. Okay. Let’s execute the query again. There you go. It’s fast. Okay let’s have a look at the react app. So the HTML file is just a simple, mostly empty file with a simple script tag that loads react app. And in the source folder I’ve got the garden app component that references adventures, the adventurous components. So let’s have a look at adventures. The adventurous component imports the custom direct query hook named use query. And the am-headless-sdk to query adventures. Then we give the am-headless client the endpoint for our GraphQL API. In this case the local one that is defined in the environment file. So this one is used to pull the actual data and this one is used for our local dev environment. And here we’ve got the query actually that we’re executing. Where we say get me the path title description and image of an adventure. And because we’re using the custom use query hook here, we’ve got some loading and error handling magic. So if it’s loading then we just return a loading adventure status. Same for error. Return no adventures, return no adventures. And if there are any adventures we render the image, the title, and the description. So let’s say we want to add the new subtal. So first what we have to do to render it, we need to query the new field. Subtitle. And once we do that we can render it. So let’s add a new tag, h3 tag for my subtitle. Okay let’s have a look at the React app. And there you go. It’s here. That’s the subtitle and for the rest of the adventures it’s a mock. Because I didn’t add a real value. So querying the data like this, it’s okay for dev environment. But for production you will want to use persistent queries. Which are basically cache queries for optimized performance. And currently there’s a session on how to speed up your website and how to use it. Persistent queries is part of it so you can watch the recording. Don’t miss it. Key takeaways. Let’s recap what we just learned. We just went over some of the fundamentals of GraphQL that powers AMheadlist via content fragments. We’ve got a little insight in the React world and we saw how simple it is to run the React app port by AMheadlist content in a dev environment running in the browser. Here again is the link to the sandbox, to the GitHub repository. Go play with it. Give it a star if you like it and if you don’t open an issue on GitHub. The conversation goes on on experience leaks and you can join the AMheadlist trial by following the link here on the right side. And once you have access to it, build your own content fragment models. Then go back to the sandbox and swap out the React endpoint with yours. Make sure you don’t run into course issues and update the query to build your own app. That’s it for me today. Thank you. And let’s move to Q&A. So the link to the sandbox. So if you want to open it in your browser, just click on that blue button here to get started. Just like I did. You can also repository locally in your local dev environment on your local machine and let it run. You don’t have to run it in the browser. Up to you. Okay, why you use JS6 files instead of JavaScript? That’s because Vite expects JS6 actually for whenever you’re writing JS6. So the compiler knows, okay, this is JS6. I’m going to optimize the code for JS6. Because as I said, JS6 is not another JavaScript. It needs a compiler. The browser doesn’t understand JS6 by default. We’ve got new documentation on Experience League for AM Headless. I don’t know if I have to link here. If anyone has to link. Thank you. There are no more questions. Okay, I’m gonna close here. Thanks again for watching and enjoy.