Installing with Next.js

Learn how to install imaginary-dev into a project that uses Next.js.

For Next.js projects, install the imaginary-dev Babel compiler plugin and change your Next.js config so that the plugin is used during the build process.

Installing the dependencies

First, install the necessary dependencies to your project:

npm install @imaginary-dev/runtime @imaginary-dev/nextjs-util
npm install --save-dev @imaginary-dev/babel-transformer

Adding imaginary-dev to your Next.js configuration

Note that imaginary-dev is not yet compatible with Next.js projects that use swc as their compiler, which is the default as of Next.js version 12. If you are using swc with the default Next.js setup, you can switch to using Babel just by creating a .babelrc or babel.config.json file and pasting in the following configuration:

{
  "presets": ["next/babel"],
  "plugins": ["module:@imaginary-dev/babel-transformer"]
}

If you already have a .babelrc file or are using a version of Next.js before version 12, add "@imaginary-dev/babel-transformer" to the plugins array in your .babelrc or babel.config.json file.

Adding your OpenAI API key

In order to use imaginary-dev, you need to get an OpenAI API key and expose it to the imaginary-dev library. If you do not have an OpenAI account, go to www.openai.com and sign up. You can then go to the API keys page to create or copy one of your OpenAI API keys.

In order for imaginary-dev to work, your API key should be accessible as an environment variable called OPENAI_API_KEY. In Next.js, you can do this easily for your development environment by editing your .env.local file (or creating a .env.local and editing it if you don't have one). Add a line like:

OPENAI_API_KEY=sk-some-api-key

Substitute in your particular OpenAI API key. If you want to learn about other ways you can set environment variables in Next.js, check out the Next.js documentation on environment variables.

Imaginary functions need to live server-side

OpenAI's API is not intended to be used directly from browsers. If you do so, you will be revealing your OpenAI API key to the world and potentially allow other people to rack up charges on your OpenAI account. For this reason, you should always use the OpenAI API on the server-side and make an API call from your browser frontend to the server. This keeps your API key safe and hidden from potential bad actors.

How you implement this depends on which version of Next.js routing you are using. In Next.js versions 12 and previous, routing was accomplished using the pages directory. In Next.js version 13 and later, there is an option to use the app directory. Integrating imaginary-dev into Next.js is different in these two different routing schemes.

Making an imaginary function in the pages directory

If you are using the pages directory, you can put your imaginary functions into files under /src/pages/api, and then use imaginePageRoute to wrap the function and turn it into a server side API call. In browser side code, you can import the API file directly and call the imaginary function as if it were a local async function:

// in /src/pages/api/titleForBlogPost
import { imaginePageRoute } from '@imaginary-dev/nextjs-util'

/**
 * This function takes in a blog post text and returns at least 5 good titles for the blog post.
 * The titles should be snappy and interesting and entice people to click on the blog post.
 *
 * @param blogPostText - string with the blog post text
 * @returns an array of at least 5 good, enticing titles for the blog post.
 *
 * @imaginary
 */
declare function titleForBlogPost(blogPostText: string): Promise<Array<string>>

export default imaginePageRoute(titleForBlogPost, '/api/titleForBlogPost')

// in browser code
import { titleForBlogPost } from './api/titleForBlogPost'

const titles = await titleForBlogPost(someText)

Making an imaginary function in the app directory

If you are using the app directory in Next.js 13 or later, you should put you imaginary fucnctions into another, non-web-accesible folder (we usually make a sibling folder to app). Then you wrap the function with imagineAppRoute, passing in the imaginary function and the URL where you plan to put the API route for it. For the server side, you need a route.ts file that imports and re-exports the GET member of the imaginary function, and from client code, you can just import the function and use it like you would any other function.

// in /src/imaginary-functions/titleForBlogPost
import { imagineAppRoute } from '@imaginary-dev/nextjs-util'

/**
 * This function takes in a blog post text and returns at least 5 good titles for the blog post.
 * The titles should be snappy and interesting and entice people to click on the blog post.
 *
 * @param blogPostText - string with the blog post text
 * @returns an array of at least 5 good, enticing titles for the blog post.
 *
 * @imaginary
 */
declare function titleForBlogPost(blogPostText: string): Promise<Array<string>>

export default imagineAppRoute(titlesForBlogPost, '/api/titlesForBlogPost')

// in /src/app/api/titlesForBlogPost
import func from '../../../imaginary-functions/titlesForBlogPost'
export const { GET } = func

// in browser code
import { titleForBlogPost } from '../../imaginary-functions/titleForBlogPost'

const titles = await titleForBlogPost(someText)

Next steps

Now that you have installed the libraries and made your OpenAI key available to the code, you should be able to write and use imaginary functions. Learn more about how to write a good imaginary function.