Installing with tsc

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

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.

Adding the OpenAI API key at the command line

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

Using a .env file to add the OpenAI API key

If you'd rather not pass your API key at the command line, you can create a .env file that collects your environment variables and loads them up into your process using the dotenv library.

Add .env on a new line of your .gitignore file to prevent yourself from accidentally checking in secrets to git. If you don't have a .gitignore file, create one and add .env to it.

Next, create a .env file in the directory from which you are running your app that looks something like:

OPENAI_API_KEY=sk-some-api-key

Then add dotenv to your project:

npm install dotenv

And finally add code to read your .env file at the entry point of your program:

import * as dotenv from 'dotenv'
dotenv.config()

If you are using a framework like Next.js, there is generally a system in place for adding secrets to a .env file, and when you deploy with a vendor like Vercel or Netlify, there is a way to set environment variables without adding to your git repo.

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.