Flotiq Next.js setup cli

This CLI adds integration between your next page and flotiq account. Running it will:

• Let you log in and add FLOTIQ_API_KEY to your .env.local
• Generate SDK which will allow easier access to flotiq data
• Generate integration between sdk and nextjs by supporting draftMode. It also adds flotiq-content tags to each request against api.flotiq.com made with sdk
• Configure Content Preview plugin on your Flotiq account [wip]
• Allow you to integrate new or existing content type
• Allow you to create sample page that uses selected content type

Supported create-next-app options:

| Feature | Yes | No | | ----------------------------------------------- | --- | --- | | Next.js version >= 15 | ✅ | ❌ | | TypeScript? | ✅ | ✅ | | ESLint?* | - | - | | Tailwind CSS? | ✅ | ✅ | | code inside a src/ directory? | ✅ | ✅ | | App Router? | ✅ | ❌ | | Turbopack for next dev?* | - | - | | customized the import alias (@/* by default)? | ✅ | ✅ |

* Inconsequential - does not influence integration output

Usage

Warning This command supports Node.js v20 or higher. You can run it with lower versions, but generation may fail, or produce incorrect code.

Initial setup

1. Run the following commands to create new Next.js project and integrate it with Flotiq:

npx create-next-app@latest <path-to-nextjs-project>
cd <path-to-nextjs-project>
npx flotiq-nextjs-setup
npm run dev

The CLI will configure Content Preview plugin and point it to your http://localhost:3000 environment.

2. Go to https://editor.flotiq.com and create new content objects
3. Use Content Preview plugin buttons to navigate either to preview, or published version of the object on your local environment.

Draft mode and Revalidation endpoints

Other than SDK, this command will create two additional api enpoints in your code:

• POST /api/flotiq/revalidate - an endpoint that clears all flotiq-related data cache in Next. It requires a header called x-editor-key with the same value as FLOTIQ_CLIENT_AUTH_KEY environment variable.

  Best way to use it is by configuring a webhook in flotiq, that will trigger this revalidation each time new changes are published.

• GET /api/flotiq/draft - and endpoint, that will start, or stop Next.js Draft Mode. It is used by Content Preview plugin in Flotiq. It accepts the following query params:

  • key - Required parameter, that must be the same value as FLOTIQ_CLIENT_AUTH_KEY environment variable. Only authorized requests can enter the draft mode and see unpublished content.
  • draft=true|draft=false - whether the draft mode should be enabled or disabled
  • redirect - where brwser should be redirected after the request. E.g. draft=true&redirect=/post/123 will enable draft mode and redirect to /post/123

Refer to Next.js Draft Mode documentation to see how to implment code supporting draft mode.

Environment variables

flotiq-nextjs-setup will add the following values to your .env files:

• FLOTIQ_API_KEY - read-only api key from flotiq. It will be required to pull data from flotiq when the server is running (or during build, if you are using static generation).
• FLOTIQ_CLIENT_AUTH_KEY - A random string, used to allow flotiq users to:
  • Preview unpublished data
  • Clear fetch cache on deployed app when objects in Flotiq are updated.
• Empty FLOTIQ_API_KEY and FLOTIQ_CLIENT_AUTH_KEY with description in .env. You can safely commit those changes to your repo
• Your FLOTIQ_API_KEY and randomally generated FLOTIQ_CLIENT_AUTH_KEY in your .env.local file. This file should not be commited in the repo to avoid credential leaks.

Regenerating flotiq SDK

Once you make changes to your content types, you'll need to regenerate the SDK To regenerate your SDK, go to root of your project and run:

npm exec flotiq-api-typegen

If are changing content types regularly and would like to regenerate the SDK automatically, run the following command to watch for changes and regenerate after each modification:

npm exec flotiq-api-typegen --watch

Next steps for users

Once integration is done, user developers can start work on their application. Once they have public instance available (stage/prod etc), they must:

• Update content preview plugin settings:
  • Change url to point to public instance
  • Update editor key to the same value as public instance FLOTIQ_CLIENT_AUTH_KEY variable.
• Create revalidation webhook:
  • type async
  • url: <Production url>/api/flotiq/revalidate
  • Header x-editor-key must have the same value as public instance FLOTIQ_CLIENT_AUTH_KEY variable.

Command Usage flow

Contributing

Starting development is simple:

yarn
yarn build:watch

Now you can run this command by running npx <path-to-flotiq-nextjs-setup-repo> <path-to-nextjs-project>.

While developing, be sure to have yarn build:watch started to compile and check types on the flight.

Prettier is mandatory and can be used as IDE plugin, or via command:

yarn codestyle # apply style fixes to all files in src