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))
INFO
You can also add .js
and .ts
extensions if you want to mix and match! Even .coffee
will work if you require coffeescript/register
or add a loader for it.
If you want to use other bundlers, check out our integrations page for a suitable plugin.