DocumentationAEMAEM TutorialsAEM Headless Tutorial

AEM Headless quick setup using the local AEM SDK setup

Last update: Tue May 14 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Beginner
  • Developer

The AEM Headless quick setup gets you hands-on with AEM Headless using content from the WKND Site sample project, and a sample React App (a SPA) that consumes the content over AEM Headless GraphQL APIs. This guide uses the AEM as a Cloud Service SDK.

Prerequisites prerequisites

The following tools should be installed locally:

1. Install the AEM SDK aem-sdk

This setup uses the AEM as a Cloud Service SDK to explore AEM’s GraphQL APIs. This section provides a quick guide to installing the AEM SDK and running it in Author mode. A more detailed guide for setting up a local development environment can be found here.

NOTE
It is also possible to follow the tutorial with an AEM as a Cloud Service environment. Additional notes for using a Cloud environment are included throughout the tutorial.

  1. Navigate to the Software Distribution Portal > AEM as a Cloud Service and download the latest version of the AEM SDK.

    Software Distribution Portal

  2. Unzip the download and copy the Quickstart jar (aem-sdk-quickstart-XXX.jar) to a dedicated folder, i.e ~/aem-sdk/author.

  3. Rename the jar file to aem-author-p4502.jar.

    The author name specifies that the Quickstart jar starts in Author mode. The p4502 specifies the Quickstart runs on port 4502.

  4. To install and start the AEM instance, open a command prompt at the folder that contains the jar file, and run the following command :

    code language-shell 
    $ cd ~/aem-sdk/author
$ java -jar aem-author-p4502.jar

  5. Provide an admin password as admin. Any admin password is acceptable, however it is recommend to use admin for local development to reduce the need to reconfigure.

  6. When the AEM service finishes installing, a new browser window should open at http://localhost:4502.

  7. Login with the username admin and the password selected during AEM’s initial start-up (usually admin).

2. Install sample content install-sample-content

Sample content from the WKND Reference site is used to accelerate the tutorial. The WKND is a fictitious life-style brand, often used with AEM training.

The WKND site includes configurations required to expose a GraphQL endpoint. In a real-world implementation, follow the documented steps to include the GraphQL endpoints in your customer project. A CORS has also been packaged as part of the WKND Site. A CORS configuration is required to grant access to an external application, more information about CORS can be found below.

  1. Download the latest compiled AEM Package for WKND Site: aem-guides-wknd.all-x.x.x.zip.

    note note
    NOTE
    Make sure to download the standard version compatible with AEM as a Cloud Service and not the classic version.

  2. From the AEM Start menu, navigate to Tools > Deployment > Packages.

    Navigate to Packages

  3. Click Upload Package and choose the WKND package downloaded in the prior step. Click Install to install the package.

  4. From the AEM Start menu, navigate to Assets > Files > WKND Shared > English > Adventures.

    Folder view of Adventures

    This is a folder of all the assets that comprise the various Adventures promoted by the WKND brand. This includes traditional media types like images and video, and media specific to AEM like Content Fragments.

  5. Click into the Downhill Skiing Wyoming folder and click the Downhill Skiing Wyoming Content Fragment card:

    Content Fragment card

  6. The Content Fragment editor opens for the Downhill Skiing Wyoming adventure.

    Content Fragment editor

    Observe that various fields like Title, Description, and Activity define the fragment.

    Content Fragments are one of the ways content can be managed in AEM. Content Fragment are reusable, presentation-agnostic content composed of structured data elements such as text, rich text, dates, or references to other Content Fragments. Content Fragments are explored in greater detail later in the quick setup.

  7. Click Cancel to close the fragment. Feel free to navigate into some of the other folders and explore the other Adventure content.

NOTE
If using a Cloud Service environment see the documentation for how to deploy a code base like the WKND Reference site to a Cloud Service environment.

3. Download and run WKND React app sample-app

One of the goals of this tutorial is to show how to consume AEM content from an external application using the GraphQL APIs. This tutorial uses an example React App. The React app is intentionally simple, to focus on the integration with AEM’s GraphQL APIs.

  1. Open a new command prompt and clone the sample React app from GitHub:

    code language-shell 
    $ git clone git@github.com:adobe/aem-guides-wknd-graphql.git
$ cd aem-guides-wknd-graphql/react-app

  2. Open the React app in aem-guides-wknd-graphql/react-app in your IDE of choice.

  3. In the IDE, open the file .env.development at /.env.development. Verify the REACT_APP_AUTHORIZATION line is uncommented and the file declares the following variables:

    code language-plain 
    REACT_APP_HOST_URI=http://localhost:4502
REACT_APP_GRAPHQL_ENDPOINT=/content/graphql/global/endpoint.json
# Use Authorization when connecting to an AEM Author environment
REACT_APP_AUTHORIZATION=admin:admin

    Ensure REACT_APP_HOST_URI points to your local AEM SDK. For convenience, this quick start connects the React app to AEM Author. Author services require authentication, so the app uses the admin user to establish its connection. Connecting an app to AEM Author is a common practice during development, as it facilitates quickly iterating on content without the need to publish changes.

    note note
    NOTE
    In a production scenario the App will connect to an AEM Publish environment. This is covered in more detail in the Production Deployment section.

  4. Install and start the React app:

    code language-shell 
    $ cd aem-guides-wknd-graphql/react-app
$ npm install
$ npm start

  5. A new browser window automatically opens the app on http://localhost:3000.

    React starter app

    A list of the adventure content from AEM is displayed.

  6. Click one of the adventure images to view the adventure detail. A request is made to AEM to return the detail for an adventure.

    Adventure Details view

  7. Use the browser’s developer tools to inspect the Network requests. View the XHR requests and observe multiple GET requests to /graphql/execute.json/.... This path prefix invokes AEM’s persisted query endpoint, selecting the persisted query to execute using the name and encoded parameters following the prefix.

    GraphQL Endpoint XHR request

4. Edit content in AEM

With the React app is running, make an update to the content in AEM and see that the change reflected in the app.

  1. Navigate to AEM http://localhost:4502.

  2. Navigate to Assets > Files > WKND Shared > English > Adventures > Bali Surf Camp.

    Bali Surf Camp folder

  3. Click into the Bali Surf Camp content fragment to open the Content Fragment editor.

  4. Modify the Title and the Description of the adventure.

    Modify content fragment

  5. Click Save to save the changes.

  6. Refresh the React app at http://localhost:3000 to see your changes:

    Updated Bali Surf Camp Adventure

5. Explore GraphiQL graphiql

  1. Open GraphiQL by navigating to Tools > General > GraphQL Query editor

  2. Select existing persisted queries on the left, and run them to see the results.

    note note
    NOTE
    The GraphiQL tool and GraphQL API is explored in more detail later in the tutorial.

Congratulations! congratulations

Congratulations, you now have an external application consuming AEM content with GraphQL. Feel free to inspect the code in the React app and continue to experiment with modifying existing Content Fragments.

Next Steps

recommendation-more-help
e25b6834-e87f-4ff3-ba56-4cd16cdfdec4