Next.js > Getting started

    Getting started

    Next.js is an exceptional tool for building modern, universal frontend applications with the power of React. It lets you get started without having to write much boilerplate code and with a set of sane defaults from which you can build upon.

    Vercel is the easiest way to deploy a production-ready highly available Next.js website, with static assets being served through the CDN automatically and built-in support for Next.js’ automatic static optimization and API routes.

    DatoCMS is the perfect companion to Next.js since it offers content, images and videos on a globally-distributed CDN, much like Vercel does for the static assets of your website. With this combo, you can have an infinitely scalable website, ready to handle prime-time TV traffic spikes, at a fraction of the regular cost.

    Our marketplace features different demo projects on Next, so you can learn and get started easily:

    Our Community has also created many great video tutorials you can follow:

    Fetching content from our GraphQL API

    Since Next 9.3, the way you fetch content from external sources is by exporting one of the following async functions from your page components:

    • getServerSideProps to fetch data on each request;

    • getStaticProps to fetch data at build time.

    // pages/index.js
    export async function getStaticProps(context) {
    return {
    props: {}, // will be passed to the page component as props
    export default Homepage(props) {

    Inside these functions, we can use any Node.JS GraphQL client (or HTTP client, really) to fetch content from DatoCMS and pass it down to your component.

    We suggest using lightweight libraries like graphql-request or unfetch since they're all you need to get the job done.

    Quick start using graphql-request

    First create a new Next.js application using create-next-app, which sets up everything automatically for you.

    To create a project, run the following command and follow the wizard:

    npx create-next-app@latest
    Next.js 13 and the experimental `app` directory

    Next.js 13 introduces new exciting features like React Server Components and the new app directory. While these features are still in beta, we suggest to keep using the stable pattern — that is, the usual pages directory.

    We'll update this documentation once the app directory is considered a stable feature. In the meantime, reply with "No" to the question "Would you like to use experimental app/ directory with this project?"

    Then enter inside the project directory, install the graphql-request package, and start the development server:

    cd my-app
    yarn add graphql-request
    yarn dev

    First you'll need to setup a GraphQL client pointing to one of our GraphQL Content Delivery API endpoints. Create a new directory lib, and inside of it create a file called datocms.js:

    import { GraphQLClient } from "graphql-request";
    export function request({ query, variables, includeDrafts, excludeInvalid }) {
    const headers = {
    authorization: `Bearer ${process.env.NEXT_DATOCMS_API_TOKEN}`,
    if (includeDrafts) {
    headers['X-Include-Drafts'] = 'true';
    if (excludeInvalid) {
    headers['X-Exclude-Invalid'] = 'true';
    const client = new GraphQLClient('', { headers });
    return client.request(query, variables);

    You can see that we're using an environment variable starting with NEXT_ so that it will be embedded into the bundle.

    To create the API token for a DatoCMS project, go in the "Settings > API Tokens" section, making sure you only give it permissions to access the (read-only) Content Delivery API.

    Next, go to pages/index.js — that is, the component that renders the homepage of our project — and define the getStaticProps function:

    import { request } from "../lib/datocms";
    const HOMEPAGE_QUERY = `query HomePage($limit: IntType) {
    allBlogPosts(first: $limit) {
    export async function getStaticProps() {
    const data = await request({
    query: HOMEPAGE_QUERY,
    variables: { limit: 10 }
    return {
    props: { data }
    export default function Home({ data }) {
    return <div>{JSON.stringify(data, null, 2)}</div>;

    The HOMEPAGE_QUERY is the GraphQL query, and of course it depends on the models available in your specific DatoCMS project. You can learn everything you need regarding how to build GraphQL queries on our Content Delivery API documentation.