Improve DX for scenarios where Next.js and Drupal integration is not working correctly

[lauriii]

There are multiple different ways how the Next.js and Drupal integration won't work correctly. This includes (but not limited to):

1. ACMS installed without default content model
2. Content model has been modified
3. Incompatible web server setup (e.g. web server not compatible with JSON:API)
4. Incorrect env variables generated by the backend

Proposed solution

Do a "preflight check" which ensures that fundamental aspects of the integration are working as expected. Fail early in case it is determined that the integration with the backend is not working as required by the Next.js app. Provide helpful error messages with links to documentation that documents how most common failures can be debugged.

The "preflight check" could check that the content model includes all content types from CONTENT_TYPES in [...slug].tsx. This would happen by checking /jsonapi which would also work as a test for ensuring that the API from the backend can be reached.

[harumijang]

Common failures with Next.js and Drupal integration

Content mismatch

In the case of a content mismatch, there are two options to fix this:

1. Reinstall Acquia CMS with both the content model and demo content enabled to ensure that the backend has all the content that the Next.js site uses.
2. Check if all the items in CONTENT_TYPES in [...slug].tsx exist in the ACMS backend and if not either add the missing content types to ACMS or edit the list of CONTENT_TYPES to match what is in ACMS.

Incompatible web server setup or incorrect environment variables generated

NOTE: The built in PHP server will not work.

Check if you are able to make a GET request to [your_acms_site]/jsonapi . If you are getting a valid response but your Next.js site isn't working, your web server might not be compatible with JSON:API.

If you are using valet as your environment, please see laravel/valet#771 (comment) for the known solution.

If you are using lando as your webserver, check your .env.local file and see if NEXT_PUBLIC_DRUPAL_BASE_URL variable, https was used. It is a known issue where it seems on lando setup, the Drupal URL generates with https when it should just be http.

Once ACMS setup is done,
try curl -X GET SITEURL with both https and http and see which one is correct then update your NEXT_PUBLIC_DRUPAL_BASE_URL accordingly.

[lauriii]

Added this to https://github.com/acquia/next-acms/wiki/Debugging-common-errors-with-Next.js-and-Drupal-integration

[lauriii]

The API for executing these checks have been added: #65.

Next step on this is to write some unit tests for the new API which was splitted to another PR since we still need to setup Jest. After that, we can make a new release of next-acms and update basic-starter to use it.

[lauriii]

We have seen significant reduction in support requests related to connecting Acquia CMS with Next.js since #65. We can open new issues in case we identify some additional use cases that should be covered.