creatium

Creatium

Build your create-bins quickly and easily

Table of contents

• 🔑 Installation
• 🤔 What is it Creatium?
• 🚀 Usage
  • Project structure
  • src/main.js
  • src/bin.js
  • src/lib.js
  • package.json
  • templates
• Api documentation
  • Classes
    • Creatium
    • CreatiumPrompt<C>
  • Type Aliases
    • CliOpts
    • Config
    • CreateOpts
    • CreateTemplateOpts
  • Variables
    • env
    • IDE
    • INSTALLER
    • OPTION
    • prompt
    • style
    • sys
• 👨‍💻 Development
• ☕ Donate
• 📜 License
• 🐦 About us

🔑 Installation

npm install creatium
# or 
pnpm add creatium
# or 
yarn add creatium
# or 
deno install creatium
# or 
bun add creatium

🤔 What is it Creatium?

Creatium is a CLI and Library for creating project templates.

Useful for create-binaries like pnpm create backan

Read more

🚀 Usage

Create a cli and a library project with creatium

Simple usage example:

Project structure

Create a project with the following structure:

📂 src
  ├── bin.js
  ├── lib.js
  └── main.js
📂 templates
  └── 📂 js-project
  └── 📂 ts-project
📄 package.json

src/main.js

Create a new instance of creatium and export it as core

import { dirname, join } from 'node:path'
import { fileURLToPath } from 'node:url'
import { version }  from './package.json'
import { Creatium } from 'creatium'

const currentDir   = join( dirname( fileURLToPath( import.meta.url ) ) )
const templatesDir = join( currentDir, '..', 'templates' )

export const core = new Creatium( {
 name: 'Simple test',
 version,
 templates : {
  js : {
   input : join( templatesDir, 'js-project' ),
   name  : 'JavaScript project',
  },
  ts : {
   input : join( templatesDir, 'ts-project' ),
   name  : 'TypeScript project',
  },
 },
} )

src/bin.js

Create a bin file and call the cli method of the core instance.

// create cli
import { core } from './main.js'
await core.cli()

src/lib.js

Create a library file and export the create function for use outside.

import { core } from './main.js'

/**
 * Create project template.
 * @param {Parameters<typeof core.build>[0]} params - The parameters required for creation.
 * @returns {Promise<Object>} A promise that resolves to the result of the creation process.
 */
export const create = async ( params ) => {

 return await core.build( params )

}

package.json

{
 "name": "create-{my-library-name}",
 "version": "0.0.1",
 "type": "module",
 "main": "src/lib.js",
 "module": "src/lib.js",
 "bin": {
  "create-{my-library-name}": "bin.js"
 },
 "files": [
  "src",
  "templates",
 ]
}

templates

Create a template folder with your templates.

Api documentation

Classes

Creatium

Class of Creatium for create project templates (CLI and Library).

Example

// ./main.js
export const core = new CreatiumPrompt({
  name: 'My Project',
  version: '1.0.0',
  prompts: {
    ...
  },
  ...
})

// ./bin.js
import { core } from './main.js'
core.cli()

// ./lib.js
import { core } from './main.js'
export const create = core.build

Constructors

new Creatium()

new Creatium(options: {
  cache: boolean;
  consts: Record<string, string>;
  intro: false | (data: HookParams) => Response<void>;
  name: string;
  onCancel: false | (data: HookParams) => Response<void>;
  opts: {
     install: false | [
        | "bun"
        | "deno"
        | "npm"
        | "pnpm"
        | "yarn", 
        | "bun"
        | "deno"
        | "npm"
        | "pnpm"
        | "yarn", ...("bun" | "deno" | "npm" | "pnpm" | "yarn")[]];
     name: boolean;
     openEditor: false | ["code" | "subl" | "webstorm", "code" | "subl" | "webstorm", ...("code" | "subl" | "webstorm")[]];
    };
  outro: false | (data: HookParams) => Response<void>;
  templates: {};
  updater: boolean;
  version: string;
 }): Creatium

Parameters

Parameter	Type	Description
options	object	-
options.cache?	boolean	Use cache Default true
options.consts?	Record<string, string>	Add consts to use in your templates.
options.intro?	false | (data: HookParams) => Response<void>	Set custom intro
options.name	string	Set name of you project
options.onCancel?	false | (data: HookParams) => Response<void>	Set custom function foor when user cancels the process
options.opts?	object	Set your prompt options
options.opts.install?	false | [ | "bun" | "deno" | "npm" | "pnpm" | "yarn", | "bun" | "deno" | "npm" | "pnpm" | "yarn", ...("bun" | "deno" | "npm" | "pnpm" | "yarn")[]]	Active/deactivate the install prompt Also, You can set the installators that you want to use.
options.opts.name?	boolean	Active/deactivate the name prompt
options.opts.openEditor?	false | ["code" | "subl" | "webstorm", "code" | "subl" | "webstorm", ...("code" | "subl" | "webstorm")[]]	Active/deactivate the openEditor prompt. Also, You can set the editors that you want to use.
options.outro?	false | (data: HookParams) => Response<void>	Set custom outro
options.templates	object	Set your template ooptions
options.updater?	boolean	Use updater Default false
options.version	string	Set version of you current project Used in for the updater notifications.

Returns

Creatium

Methods

build()

build(values?: {
  input: string;
  install: PkgManager;
  name: string;
  openEditor: TextEditor;
  output: string;
 }, opts?: CreateOpts): Promise<{
  input: string;
  install: undefined;
  name: undefined;
  openEditor: undefined;
  output: string;
}>

A simplified version of the build method from the main class.

Parameters

Parameter	Type	Description
values?	object	The values to override the CLI prompts. If not set, the CLI prompts will be executed.
values.input?	string	Set the input path or the template key
values.install?	PkgManager	Set the installer
values.name?	string	Set the name of the template
values.openEditor?	TextEditor	Open editor
values.output?	string	Set the output path
opts?	CreateOpts	The options to pass to the CLI.

Returns

Promise<{ input: string; install: undefined; name: undefined; openEditor: undefined; output: string; }>

A promise resolving to the prompt values obtained after executing the CLI.

Name	Type
input?	string
install?	undefined
name?	undefined
openEditor?	undefined
output?	string

Examples

// simple usage
await core.build()

// custom usage
await core.build( { args : process.argv.slice(4), hideBin : false } )

cli()

cli(props?: CliOpts): Promise<{
  input: string;
  install: undefined;
  name: undefined;
  openEditor: undefined;
  output: string;
}>

A simplified version of the cli method from the main class. Initializes and executes the command-line interface (CLI) process.

Parameters

Parameter	Type	Description
props?	CliOpts	Optional CLI options to configure the initialization process.

Returns

Promise<{ input: string; install: undefined; name: undefined; openEditor: undefined; output: string; }>

A promise resolving to the prompt values obtained after executing the CLI.

Name	Type
input?	string
install?	undefined
name?	undefined
openEditor?	undefined
output?	string

Examples

// simple usage
await core.cli()

// custom usage
await core.cli( { args : process.argv.slice(4), hideBin : false } )

---

CreatiumPrompt<C>

Customizable class of Creatium for create project templates (CLI and Library).

Example

//////////////// main.js ///////////////////

const core = new CreatiumPrompt({
  name: 'My Project',
  version: '1.0.0',
  prompts: {
    ...
  },
  ...
})

//////////////// bin.js ///////////////////

import { core } from './main.js'
const res = await core.cli()
// do something with res...
await core.createTemplate( res )

//////////////// lib.js ///////////////////

import { core } from './main.js'
export const create = async (args) => {
  const res = await core.build( args )
  // do something with res...
  await core.createTemplate( res )
}

Type Parameters

Type Parameter	Default type	Description
C extends Config	Config

Accessors

debugMode

Set Signature

set debugMode(value: boolean): void

Force debug mode

Parameters

Parameter	Type
value	boolean

Returns

void

Constructors

new CreatiumPrompt()

new CreatiumPrompt<C>(config: C): CreatiumPrompt<C>

Parameters

Parameter	Type
config	C

Returns

CreatiumPrompt<C>

Methods

build()

build(values?: { [K in string | number | symbol]: { [K in string | number | symbol]: { [K in string | number | symbol]?: { [K in string | number | symbol]: ((...)[(...)] extends Object ? (...) extends (...) ? (...) : (...) : never)[K] } }[K] }[K] }, opts?: CreateOpts): Promise<{ [K in string | number | symbol]: { [K in string | number | symbol]?: { [K in string | number | symbol]: (C["prompt"][K] extends Object ? T extends keyof OptionsClasses ? { [K in (...) | (...) | (...)]: (...)[(...)] } : never : never)[K] } }[K] }>

Initialize the CLI and executes the callback function passed in the config.

Parameters

Parameter	Type	Description
values?	{ [K in string | number | symbol]: { [K in string | number | symbol]: { [K in string | number | symbol]?: { [K in string | number | symbol]: ((...)[(...)] extends Object ? (...) extends (...) ? (...) : (...) : never)[K] } }[K] }[K] }	The values to override the CLI prompts. If not set, the CLI prompts will be executed.
opts?	CreateOpts	The options to pass to the CLI.

Returns

Promise<{ [K in string | number | symbol]: { [K in string | number | symbol]?: { [K in string | number | symbol]: (C["prompt"][K] extends Object ? T extends keyof OptionsClasses ? { [K in (...) | (...) | (...)]: (...)[(...)] } : never : never)[K] } }[K] }>

The result of the callback function.

cli()

cli(props?: CliOpts): Promise<{ [K in string | number | symbol]: { [K in string | number | symbol]?: { [K in string | number | symbol]: (C["prompt"][K] extends Object ? T extends keyof OptionsClasses ? { [K in (...) | (...) | (...)]: (...)[(...)] } : never : never)[K] } }[K] }>

Initializes and executes the command-line interface (CLI) process.

Parameters

Parameter	Type	Description
props?	CliOpts	Optional CLI options to configure the initialization process.

Returns

Promise<{ [K in string | number | symbol]: { [K in string | number | symbol]?: { [K in string | number | symbol]: (C["prompt"][K] extends Object ? T extends keyof OptionsClasses ? { [K in (...) | (...) | (...)]: (...)[(...)] } : never : never)[K] } }[K] }>

A promise resolving to the prompt values obtained after executing the CLI.

Examples

// simple usage
await core.cli()

// custom usage
await core.cli( { args : process.argv.slice( 4), hideBin : false } )

createTemplate()

createTemplate(values: CreateTemplateOpts): Promise<void>

Create a new project template.

Parameters

Parameter	Type	Description
values	CreateTemplateOpts	The values to create the template.

Returns

Promise<void>

• A promise that resolves when the template is created.

Examples

// basic usage
await core.createTemplate( { input : 'my/template/path', output : 'my/project/path' } )

// custom usage
await core.createTemplate( {
  input : 'my/template/path',
  output : 'my/project/path',
  install : 'pnpm',
  open : 'vscode',
  consts : {
    version : '1.0.0',
    header : '// Template generated by Creatium. a project from PigeonPosse',
  },
} )

Properties

Property	Type
config	C
utils	__module

Type Aliases

CliOpts

type CliOpts: {
  args: string[];
  hideBin: boolean;
};

Type declaration

Name	Type	Description
args?	string[]	Arguments to pass to the command Default process.argv.slice(2)
hideBin?	boolean	Hide the first two arguments Default false

---

Config

type Config: {
  cache: boolean;
  hooks: {
     afterPrompt: <D>(data: D) => Response<D | undefined>;
     beforePrompt: <D>(data: D) => Response<D | undefined>;
    };
  intro: (data: HookParams) => Response<void> | false;
  name: string;
  onCancel: (data: HookParams) => Response<void> | false;
  outro: (data: HookParams) => Response<void> | false;
  prompt: OptionsParams;
  updater: boolean;
  version: string;
};

Type declaration

Name	Type	Description
cache?	boolean	Use cache Default true
hooks?	{ afterPrompt: <D>(data: D) => Response<D | undefined>; beforePrompt: <D>(data: D) => Response<D | undefined>; }	hooks for
hooks.afterPrompt?	<D>(data: D) => Response<D | undefined>	-
hooks.beforePrompt?	<D>(data: D) => Response<D | undefined>	-
intro?	(data: HookParams) => Response<void> | false	Set custom intro
name	string	Set name of you project
onCancel?	(data: HookParams) => Response<void> | false	Set custom function foor when user cancels the process
outro?	(data: HookParams) => Response<void> | false	Set custom outro
prompt	OptionsParams	Set you prompts config
updater?	boolean	Use updater Default false
version	string	Set version of you current project Used in for the updater notifications.

---

CreateOpts

type CreateOpts: CliOpts & {
  activeCli: boolean;
};

Type declaration

Name	Type	Description
activeCli?	boolean	Options for activate cli. Default true

---

CreateTemplateOpts

type CreateTemplateOpts: {
  consts: Record<string, string>;
  input: string;
  install: PkgManager;
  name: string;
  openEditor: TextEditor;
  output: string;
};

Type declaration

Name	Type	Description
consts?	Record<string, string>	Add consts to use in your templates.
input?	string	Set the input path or the template key
install?	PkgManager	Set the installer
name?	string	Set the name of the template
openEditor?	TextEditor	Open editor
output?	string	Set the output path

Variables

env

const env: {
  isBrowser: boolean;
  isBun: boolean;
  isDeno: boolean;
  isJsDom: boolean;
  isNode: boolean;
  isWebWorker: boolean;
 } = _env;

Environment functions

Type declaration

Name	Type
isBrowser	boolean
isBun	boolean
isDeno	boolean
isJsDom	boolean
isNode	boolean
isWebWorker	boolean

---

IDE

const IDE: {
  NONE: 'none';
  SUBLIME: 'subl';
  VSCODE: 'code';
  WEBSTORM: 'webstorm';
};

Type declaration

Name	Type	Default value
NONE	"none"	'none'
SUBLIME	"subl"	'subl'
VSCODE	"code"	'code'
WEBSTORM	"webstorm"	'webstorm'

---

INSTALLER

const INSTALLER: {
  BUN: 'bun';
  DENO: 'deno';
  NONE: 'none';
  NPM: 'npm';
  PNPM: 'pnpm';
  YARN: 'yarn';
};

Type declaration

Name	Type	Default value
BUN	"bun"	'bun'
DENO	"deno"	'deno'
NONE	"none"	'none'
NPM	"npm"	'npm'
PNPM	"pnpm"	'pnpm'
YARN	"yarn"	'yarn'

---

OPTION

const OPTION: {
  array: 'array';
  boolean: 'boolean';
  install: 'install';
  multiselect: 'multiselect';
  name: 'name';
  number: 'number';
  openEditor: 'openEditor';
  output: 'output';
  path: 'path';
  select: 'select';
  template: 'template';
  text: 'text';
  void: 'void';
};

Object of the CREATIUM types

Type declaration

Name	Type	Default value
array	"array"	'array'
boolean	"boolean"	'boolean'
install	"install"	'install'
multiselect	"multiselect"	'multiselect'
name	"name"	'name'
number	"number"	'number'
openEditor	"openEditor"	'openEditor'
output	"output"	'output'
path	"path"	'path'
select	"select"	'select'
template	"template"	'template'
text	"text"	'text'
void	"void"	'void'

---

prompt

const prompt: {
  box: (opts: {
     opts: Options;
     type: PromptLineMethod;
     value: string;
    }) => void;
  columns: (opts: {
     opts: GlobalOptions;
     type: PromptLineMethod;
     value: ColumnData;
    }) => void;
  log: {
     error: (message: string) => void;
     info: (message: string) => void;
     message: (message?: string, { symbol }?: LogMessageOptions) => void;
     step: (message: string) => void;
     success: (message: string) => void;
     warn: (message: string) => void;
     warning: (message: string) => void;
    };
  number: (opts: {
     defaultValue: string;
     errorText: string;
     initialValue: string;
     message: string;
     placeholder: string;
     validate: (value: string) => string | void;
    }) => Promise<number | symbol>;
  table: (opts: {
     opts: TableUserConfig;
     type: PromptLineMethod;
     value: TableData;
    }) => void;
  cancel: void;
  confirm: Promise<boolean | symbol>;
  group: Promise<{ [P in string | number | symbol]: PromptGroupAwaitedReturn<T>[P] }>;
  groupMultiselect: Promise<symbol | Value[]>;
  intro: void;
  isCancel: value is symbol;
  multiselect: Promise<symbol | Value[]>;
  note: void;
  outro: void;
  password: Promise<string | symbol>;
  select: Promise<symbol | Value>;
  selectKey: Promise<symbol | Value>;
  spinner: {
     message: (msg?: string) => void;
     start: (msg?: string) => void;
     stop: (msg?: string, code?: number) => void;
    };
  tasks: Promise<void>;
  text: Promise<string | symbol>;
 } = _prompt;

Prompt functions

Type declaration

Name	Type	Description
box	(opts: { opts: Options; type: PromptLineMethod; value: string; }) => void	-
columns	(opts: { opts: GlobalOptions; type: PromptLineMethod; value: ColumnData; }) => void	-
log	{ error: (message: string) => void; info: (message: string) => void; message: (message?: string, { symbol }?: LogMessageOptions) => void; step: (message: string) => void; success: (message: string) => void; warn: (message: string) => void; warning: (message: string) => void; }	-
log.error	(message: string) => void	-
log.info	(message: string) => void	-
log.message	(message?: string, { symbol }?: LogMessageOptions) => void	-
log.step	(message: string) => void	-
log.success	(message: string) => void	-
log.warn	(message: string) => void	-
log.warning	(message: string) => void	alias for log.warn().
number	(opts: { defaultValue: string; errorText: string; initialValue: string; message: string; placeholder: string; validate: (value: string) => string | void; }) => Promise<number | symbol>	-
table	(opts: { opts: TableUserConfig; type: PromptLineMethod; value: TableData; }) => void	-
cancel()	void	-
confirm()	Promise<boolean | symbol>	-
group()	Promise<{ [P in string | number | symbol]: PromptGroupAwaitedReturn<T>[P] }>	Define a group of prompts to be displayed and return a results of objects within the group
groupMultiselect()	Promise<symbol | Value[]>	-
intro()	void	-
isCancel()	value is symbol	-
multiselect()	Promise<symbol | Value[]>	-
note()	void	-
outro()	void	-
password()	Promise<string | symbol>	-
select()	Promise<symbol | Value>	-
selectKey()	Promise<symbol | Value>	-
spinner()	{ message: (msg?: string) => void; start: (msg?: string) => void; stop: (msg?: string, code?: number) => void; }	-
tasks()	Promise<void>	Define a group of tasks to be executed
text()	Promise<string | symbol>	-

---

style

const style: {
  box: (text: string, options?: Options) => string;
  color: ChalkInstance;
  columns: <Data>(data: Data, options?: GlobalOptions) => string;
  gradient: (txt: string, colors: GradientColors, opts?: GradientOpts) => string;
  line: (__namedParameters: {
     align: 'center';
     lineChar: '⎯';
     title: string;
    }) => string;
  table: (data: TableData, options?: TableUserConfig) => string;
 } = _style;

Style functions

Type declaration

Name	Type
box	(text: string, options?: Options) => string
color	ChalkInstance
columns	<Data>(data: Data, options?: GlobalOptions) => string
gradient	(txt: string, colors: GradientColors, opts?: GradientOpts) => string
line	(__namedParameters: { align: 'center'; lineChar: '⎯'; title: string; }) => string
table	(data: TableData, options?: TableUserConfig) => string

---

sys

const sys: __module = _sys;

System functions

---

👨‍💻 Development

creatium is an open-source project and its development is open to anyone who wants to participate.

☕ Donate

Help us to develop more interesting things.

📜 License

This software is licensed with GPL-3.0.

🐦 About us

PigeonPosse is a ✨ code development collective ✨ focused on creating practical and interesting tools that help developers and users enjoy a more agile and comfortable experience. Our projects cover various programming sectors and we do not have a thematic limitation in terms of projects.

---