flotiq-nextjs-setup
v0.11.1
Published
Downloads
117
Readme
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
- 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.
- Go to https://editor.flotiq.com and create new content objects
- 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 calledx-editor-key
with the same value asFLOTIQ_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 asFLOTIQ_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 disabledredirect
- 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
andFLOTIQ_CLIENT_AUTH_KEY
with description in.env
. You can safely commit those changes to your repo - Your
FLOTIQ_API_KEY
and randomally generatedFLOTIQ_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 instanceFLOTIQ_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