Getting started #

If you have now been convinced that Civet is right for your current/next project, here is how to set up your environment to get productive right away and have a Good Time℠.

Quick start #

Try out the transpiler interactively in the Playground.

Or transpile Civet code interactively in the command-line REPL:

npx @danielx/civet -c

Or run Civet code directly in the command-line REPL:

npx @danielx/civet

Installation #

To install Civet package as a dev dependency in your project:

npm i -D @danielx/civet

For command-line usage outside package.json scripts, it is also helpful to install Civet globally, which enables a civet command-line interface:

npm i -g @danielx/civet

The instructions below assume such a global install; if you do not want to, use npx @danielx/civet in place of civet.

To use TypeScript for type checking, create a tsconfig.json file. For example:

{
  "compilerOptions": {
    "strict": true,
    "jsx": "preserve",
    "lib": ["es2021"],
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "esModuleInterop": true
  },
  "ts-node": {
    "transpileOnly": true,
    "compilerOptions": {
      "module": "ES2020"
    }
  }
}

Executing code #

Simple execution of a .civet source file (CommonJS or ESM):

civet source.civet ...args...

Directly execute a .civet CommonJS source file in Node:

node -r @danielx/civet/register source.civet ...args...

Directly execute a .civet ESM source file in Node:

node --loader @danielx/civet/esm source.civet ...args...

Directly execute a .civet or .ts source file that mixes .civet and .ts code, using ts-node:

node --loader ts-node/esm --loader @danielx/civet/esm source.civet ...args...

Transpilation #

Simple compilation of one civet source file to TypeScript:

npx @danielx/civet < source.civet > output.ts

Compile several .civet source files to .civet.tsx (default extension):

civet -c *.civet

Compile several .civet source files to .js:

civet --js -c *.civet -o .js

To see all command-line options:

civet --help

To transpile within an ESM NodeJS app (assuming npm i -D @danielx/civet):

import {compile} from "@danielx/civet"
const tsCode = compile(civetCode)
const tsCodeWithSourceMap = compile(civetCode, {inlineMap: true})
const jsCode = compile(civetCode, {js: true})

To transpile within a CommonJS NodeJS app (assuming npm i -D @danielx/civet):

{compile} = require("@danielx/civet")
// rest as above

Building a project #

We strongly recommend using esbuild as your project bundler:

import esbuild from 'esbuild'
import civetPlugin from '@danielx/civet/esbuild-plugin'

esbuild.build({
  // ...
  plugins: [
    civetPlugin()
  ]
}).catch(() => process.exit(1))

If you want to use other bundlers, check out our integrations page for a suitable plugin.