cogs-box

interface to config files for geenee projects.

Why

It's a pain to maintain a geenee template.

What

A Configuration type, as well as simple getConfig and setConfig functions to keep them stored in a file.

Usage

Add the package:

npm i gear-box

A config file in geenee is called config.yml and is stored in the root directory of a template.

You can read and write to the file easily:

  const templateDir = __dirname + '/template'

  const config = await getConfig(templateDir)

  // read and modify config...

  await setConfig(templateDir, config) // saves the new version

About Configurations

Every template needs a config YAML file, which is $TEMPLATE/config.yml.

Check out the one for this package for an example.

Creating Your Config File

Add the following, substituting as appropriate between the less than and greater than signs:

name: <Template Name>
version: 1.0
category: <Description>

For category, currently you can put whatever you'd like to describe it. You could probably put the name of a common Framework if it's relevant.

The category may be used soon for classification in a registry of shared templates. In theory, is should be possible to switch between templates of a shared type that meet criteria. You may also create switchable templates yourself, which will allow you to switch between various looks or other options.

Dirs List

You also need to add a list of dirs. Use this as an example (you only need custom unless you also want dynamic components that connect to a server):

dirs:
    custom: src/custom
    components: src/components
    queries: src/components/source-props

The dirs are all relative to the code base generated by users of your app.

• components is where any dynamically generated components will be.
• static is a place where static files are generated.
• custom is a place where they can put additional custom code.
• queries is optional if you will be requiring queries to a backend.

Custom File Filter

You need to tell geenee what files to search for in a code base when testing or generating code. format.customFileFilter is a glob pattern.

This example (which is for a TypeScript code base), uses one pattern that captures ts and md files:

format:
  customFileFilter: '*.{ts,tsx,md}'

The suffixes shown can be replaced as needed. So for a Javascript code base, you could put '.{js}'. If you are using jsx, you could put '.{js, jsx}'.

As with all glob patterns, you can also list multiple patterns:

format:
  customFileFilter: '+(*.{ts,tsx,md)|.eslintignore}'

You can add other settings as specified below, but if you are following the sequence of steps to create a template you can return now.

Other Settings

To get started, you can copy something like this sample into config.yml and modify as needed:

format:
  customFileFilter: '.{js,jsx,md}'

componentTypes:
  creation:
    suffix: CreationForm
    singular: true
  list:
    singular: false
  single:
    singular: true

dataFunctionTypes:
  selectable:
    components:
      - list
      - single
    requiresSource: true
    nodeType: selectable
  constrain:
    components: null
  create:
    components:
      - list
      - single
      - creation
  use:
    components:
      - list
      - single
    requiresSource: true
  property:
    components:
      - list
      - single

Values in the Config File

• componentTypes [More documentation is planned shortly for component types.]

• dataFunctionTypes [More documentation is planned shortly for data function types types.]

API

Functions

getConfig(templateDir: string)

Returns a Configuration. Will return an error if the directory given does not exist, has no config.yml file, or has a defective one.

setConfig(templateDir: string, config: Configuration)

Writes a config file config.yml based on config to the directory templateDir.

WARNING: Will simply overwrite an existing config.yml file.

Will return an error if the directory does not exist.

Configuration Interface

You can see the configuration interface code for precise information about the exported types.