Imaginary Programming is a way to use AI to define implementation-free functions in TypeScript. When you have installed imaginary-dev into your project, you can define a function like this:

/**
 * 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>>;

And then you can just start calling the function from the rest of your code, without implementing the function at all.

Under the covers, imaginary-dev has a compiler plugin that finds imaginary functions like this one and replaces them with runtime calls to OpenAI's GPT. The runtime asks GPT something like "if a function like this existed and I gave it the following arguments, what would the function return?". GPT becomes the runtime engine of your imagined function!

What's more, GPT works in raw text, but you can send in arguments and receive results in any JSON format you desire.

Imaginary Programming is great for classification, finding structure in unstructured text, and generating creative content. See imaginary.dev for more.

Installing imaginary-dev for Next.js projects

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
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 to Next.js

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.

In Next.js, you can put your imaginary functions into files under /src/pages/api, and then use makeImaginaryNextFunction 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 /pages/api/titleForBlogPost
import { makeImaginaryNextFunction } 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 makeImaginaryNextFunction(
  titleForBlogPost,
  "/api/titleForBlogPost"
);

// in browser code
import { titleForBlogPost } from "./api/titleForBlogPost";

const titles = await titleForBlogPost(someText);

Installing imaginary-dev for Babel projects

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

Installing the dependencies

First, install the necessary dependencies to your project:

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

Adding imaginary-dev to your Babel configuration

Second, add "@imaginary-dev/babel-plugin-transformer-prompt-js" to the plugins array in your Babel configuration. Your Babel configuration is likely in one of the following places:

• A JSON file called babel.config.json, .babelrc.json, or .babelrc
• Your project's package.json under a key named babel
• A JavaScript file called babel.config.js or .babelrc.js
• The CLI argument --plugins, if you are using the Babel command line interface
• The second argument to transformSync if you have written code to invoke the Babel compiler.

For more information on Babel configuration, see the Babel documentation on the subject.

Adding your OpenAI API key

In order to use imaginary-dev, you also 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.

For running locally on your developer machine you can pass environment variables at the command line, like:

OPENAI_API_KEY=sk-some-api-key node myfile.js

Installing imaginary-dev for TypeScript projects

For projects that already use the standard TypeScript compiler (tsc) as part of their build process, you will need to replace tsc with ttsc from the excellent ttypescript project. ttsc is a drop-in replacement for tsc that allows the use of compiler plugins, like the one that is required for imaginary-dev to run. Replacing tsc with ttsc will not change the version of TypeScript that you use. You will also need to install the imaginary-dev compiler plugin and edit your TypeScript config to use that plugin.

Installing the dependencies

First, install the necessary dependencies to your project:

npm install @imaginary-dev/runtime
npm install --save-dev @imaginary-dev/typescript-transformer ttypescript

Swap out tsc for ttsc

Next, find where in your project tsc is invoked as part of your project's build. Commonly, this in an npm script defined in package.json. Replace tsc with ttsc (note the extra "t" at the beginning). For example, if your project is built with the command npm run build, look in your package.json file, and you'll probably see a line like this:

{
  "scripts": {
    "build": "tsc"
  }
}

To swap out the compiler, all you need to do is change that to:

{
  "scripts": {
    "build": "ttsc"
  }
}

ttsc will pick up your existing TypeScript configuration and support all the same configuration settings as tsc.

Adding imaginary-dev to your TypeScript configuration

Third, add the following plugins line to the compilerOptions section of your tsconfig.json file:

{
  "compilerOptions": {
    // add the following line to your tsconfig.json:
    "plugins": [{ "transform": "@imaginary-dev/typescript-transformer" }]
  }
}

This tells the compiler to transform imaginary functions when it compiles your code.

Adding your OpenAI API key

In order to use imaginary-dev, you also 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.

For running locally on your developer machine you can pass environment variables at the command line, like:

OPENAI_API_KEY=sk-some-api-key node myfile.js