Hello World starter

This starter is a good choice if you want to kick off a new project after you gained some familiarity with Uniform.

The Hello World starter is the most basic starter; it ships with a single component and a single page.

The starter is implemented in Next.js 13+ and Nuxt 3 and includes:

  • Live preview for all page types and in-line editing enabled.
  • Personalization and A/B testing.
  • The ability to manage sitemap in project map.

Here is a live version of the starter.

While you can git clone this starter and set it up manually, Uniform recommends using the CLI if you have limited experience with Uniform.

  1. Open a terminal, and navigate to where you want your local project to be created.

  2. Run this in terminal or command line:

    npx @uniformdev/cli@latest new

    and enter the following values when prompted:

    PromptResponse
    Can we open a browser window to get a Uniform auth token?Y
    Paste your Uniform auth token [hidden][Paste in the value from your clipboard]
    Hey [username]! Choose a Uniform team for your new project[Select appropriate team name]
    Choose your preferred frameworkNext.js
    Choose one of the Uniform starters (for Next.js)Hello World (Page Router) or Hello World (App Router)
    What's your project name?[Give a descriptive name for your project]

    About this step

    This command performs a number of tasks for you:

    1. Creates a new Uniform project.
    2. Populates the Uniform project with sample content.
    3. Creates a new front-end application using your preferred framework connected to your new Uniform project.
    4. Starts the new front-end app locally.

  3. Open your browser to http://localhost:3000 to access the front-end.

Now you can see how a user can make changes to the site content and layout without changing any code in the front-end application.

  1. In Uniform, open your project.

  2. Navigate to Canvas > Compositions.

    compositions

  3. Click the composition Home.

    visual-canvas

    About this step

    You will see your Next.js application along with the settings for the composition.

  4. In the left nav, navigate to Page > Content > Personalized variations > Welcome.

    welcome-component-selected

    About this step

    You have selected the Hero component that displays the welcome message. There is a React component in your Next.js app that corresponds to this component. The mapping of which React component is used to render a Uniform component is configured in the Next.js app.

  5. On the right, in the section Parameters, change the value of the parameter Title to the following:

    You're in!
    title-parameter-changed

    About this step

    The parameters on the Uniform component are passed as props to the React component.

  6. Click Publish to save and publish your change.

Summary

Now you have a Uniform project that defines a personalized experience for the index page of modern web application. In the next sections you will build off of this starting point to learn how web applications powered by Uniform are built.

Add a new page#

Goals

  1. Add a new page to the site without changing any code.
  2. Update site navigation without changing any code.
  3. Add a Hero component to the new page without changing any code.

  1. If you are in Canvas, click .

    exit-visual-canvas

  2. In the left menu, click Project Map.

  3. Click Add node.

  4. Enter the following values:

    Section/fieldAction
    Node typeselect Composition
    Compositionclick Page
    Nameenter About
    Locationclick Home
    add-node

  5. Click Save & open Canvas.

  6. On the right, in the section Parameters, change the value of the parameter Meta Title to the following:

    About

  7. Click Publish.

Add a Hero component to the page#

  1. In Canvas, click the green circle with a on it.

    empty-slot

  2. Click Hero.

    add-hero-component-to-slot

  3. Enter the following values:

    ParameterValue
    TitleAbout Us
    DescriptionThis section explains all about us.
    hero-parameters-set

  4. Click Publish.

  5. Open your browser to http://localhost:3000/about.

Summary

Now you have added a new page to your site and have controlled its layout without having to write any code. In the next section you will develop a new component and add it to the page.

View new page#

  1. Open your browser to http://localhost:3000.
  2. Click the link About in the site navigation to view the page you created.

    About this step

    This link appears in the site navigation because you added a new node to the Project Map. The front-end application has a component that renders the nodes in the Project Map as navigation links.

Build a new component managed in Canvas.

Goals

  1. Create a new component definition in Component Library
  2. Create a new React component.
  3. Register your new React component with Uniform SDK.
  4. Add your new component to a page.
Step-by-step instructions on how to add a new component to the Uniform Component Library.
  1. In Uniform, navigate to Canvas > Component Library.
  2. Click Add component.
  3. Enter the following values:
    FieldValue
    Component NameCall to Action
    Public IDcallToAction
    Component iconPhone
  4. Click Add parameter.
  5. Enter the following values and click OK
    FieldValue
    Parameter NameTitle
    Public IDtitle
    TypeText
  6. Add another parameter using the following values:
    FieldValue
    Parameter NameText
    Public IDtext
    TypeRichText
  7. From the dropdown Title Parameter, select Title.
  8. Click Save and close.

The component you created in Uniform needs to be implemented in your front-end application.

  1. Add the following file to your front-end application:

    /components/callToAction.tsx

    import { registerUniformComponent, ComponentProps, UniformText } from "@uniformdev/canvas-react"; import { UniformRichText } from "@uniformdev/canvas-next"; //ComponentProps makes the Uniform composition available //to the React component. Using this type is optional. type HeroProps = ComponentProps<{ title: string; text?: string; }>; const CallToAction: React.FC<HeroProps> = () => ( <div> <UniformText className="title" parameterId="title" as="h1" /> <UniformRichText parameterId="description" className="text" /> </div> ); // //Map the React component to the Uniform component's public ID. registerUniformComponent({ type: "callToAction", component: CallToAction, }); export default CallToAction;
  2. Edit the following file:

    components/canvasComponents.ts

    // IMPORTANT: all Canvas managed components have to be imported here in order to be discovered by the <UniformSlot /> and rendered: import "./Hero"; import "./CallToAction";
  1. In Uniform, navigate to Canvas > Component Library.
  2. Click Page.
  3. Navigate to Slots > Content.
  4. Under Allowed Components, click Call to Action.
  5. Click OK.
  6. Click Save and close.

Add component to page#

Step-by-step instructions on how to add a new component to a composition.
  1. Navigate to Project Map.
  2. Click About.
  3. Click on the Hero component.
  4. Click the green circle with a on it.
  5. Click Call to Action.
  6. Enter the following values:
    ParameterValue
    TitleJoin us today!
    TextWe are ready and waiting for you. Sign up for our newsletter.
  7. Click Publish.
  8. Open your browser to http://localhost:3000/about.

Summary

Now you have updated the page on your site to incorporate a newly created component. You were able to set content on the component without having to make any code changes.

  1. Check out other starters that contain more features.
  2. Connect external data into one of the components.
  3. Add an integration for a system that's a part of your stack.
  4. Try out personalization.
  5. Deploy to your preferred delivery platform. Uniform offers special capabilities with some CDNs,such as edge-side personalization. Please refer to the list of CDN integrations.
Last modified