First Steps

Here you find a brief overview of the first steps I always do after installing the Query API. These are all optional but I think they make sense.

Configure Cors Origins

To prevent CORS origin errors in your frontend, you should configure allowed origins in the config/app.web.php file. Add the following configuration to define which domains are allowed to make cross-origin requests:

<?php

  return [
      'as corsFilter' => [
          'class' => \craft\filters\Cors::class,

          // Add your origins here
          'cors' => [
              'Origin' => [
                  'http://localhost:3000',
              ],
              'Access-Control-Request-Method' => ['GET'],
              'Access-Control-Request-Headers' => ['*'],
              'Access-Control-Allow-Credentials' => true,
              'Access-Control-Max-Age' => 86400,
              'Access-Control-Expose-Headers' => [],
          ],
      ],
  ];

Headless Mode

Set headless mode in your config/general.php to true.

Enable Preview

To enable previewing entries etc. you have to tell Craft CMS, where the frontend lives.

Add a new env var:

WEBSITE_URL="http://localhost:3000"

Add new alias to Craft CMS:

Now add this recently created env var to your config/general.php as an alias.

->aliases([
    '@websiteUrl' => getenv('WEBSITE_URL'),
])

Change Site URL

And finally go to your control panel settings -> sites -> and change the base URL of your Site. If you click on the Craft CMS logo in the left top corner, you should land on your defined WEBSITE_URL

Native Image Transforms

Currently the Query API supports Craft's native image transforms and ImagerX out of the box. If you are using ImagerX, you can continue reading in the ImagerX Guide.

As of now Craft does not support a global definition of srcSet's, but we need to define these somewhere. You can do that by adding a file named query-api.php in the config folder. Here you can configure the Query API and define image srcSets per image transform.

This can look like that:

<?php

return [
    'assetTransforms' => [
        'portrait' => [
            'srcset' => ['100w', '200w'],
            'generateOnSaveVolumes' => ['graphics']
        ],
        'landscape' => [
            'srcset' => ['0.5x', '1x'],
            'generateOnSaveVolumes' => true,
        ],
    ],
];

generateTransformsBeforePageLoad

Another thing that makes sense is to set the generateTransformsBeforePageLoad setting in the config/general.php to true. This makes sure, image generation happens before the response comes back.

You can read more about that in the offical docs of craft.

Enable Typescript Generation

The Query API comes with some black magic that generates TypeScript definitions based on your project yamls. It offers settings to automatically regenerate this TypeScript file whenever the project config changes.

To set this up, you need to have your frontend in the same repository. Otherwise it get's tricky to copy the TypeScript file to the right place.

Start by adding a file named query-api.php in the config folder.

<?php

return [
    '*' => [],
    'dev' => [
        // Automatic regeneration on project config changes
        'typeGenerationMode' => 'auto',
        // // Set the path where the generated TS file should be saved
        'typeGenerationOutputPath' => '@root/frontend/shared/types/base.ts',
    ]
];