CLI configuration file

[tomrav]

Description

Stylable currently supports one build flow.
We want the ability to structure a program into smaller pieces and give the ability to share configuration between them.

When working with multi packages project that uses Stylable CLI, you will need to call stc from each package and specify the configuration inline. For example, stc --outDir dist.
The solution that we are looking for is that the user will configure his project in one place (regardless of whether it is one package or many).

Current main issues

• Projects are running stc multiple times and not once.
• There is no watch mode that understands the dependency graph and builds them in the correct package order.

Goals

• Parsing configuration from a file js or json for the example - stylable.config.js. Then the user can configure his project easily and use presets or share code (it also can be typed).
• Give the option to hook into process life cycles.
• Using one configuration from the root for the whole multi-package project.
  We can have a field named projects which can be an array of package names or a record that the key represents a request that can be a package name or a matching pattern and the value can be preset, presets, partial configuration, or object with preset and configuration override.

export type Presets = Record<string, PartialBuildOptions>;

export type Projects =
    | Array<string | [string, ProjectEntryValues]>
    | Record<string, ProjectEntryValues>;

export interface MultipleProjectsConfig extends Partial<SingleProjectConfig> {
    presets?: Presets;
    projects: Projects;
    projectsOptions?: {
        resolveRequests?: ResolveRequests;
    };
}


export type ProjectEntryValue<T extends string> =
    | T
    | PartialBuildOptions
    | {
          preset?: T;
          presets?: Array<T>;
          options: PartialBuildOptions;
      };

export type ProjectEntryValues<T extends string> =
    | ProjectEntryValue<T>
    | Array<ProjectEntryValue<T>>;

By default the packages must be under workspaces field in the root package json.

• As stated above, we will give the option to declare presets available in the project.
  We could also provide common presets that will have the options configured in the documentation for the user to see and use. For example, like stcss-lib, css-lib, css-in-js-lib, ssr, etc.

• The user can provide his own resolve requests method.

Preset examples:

• Usages in projects

{
    "presets": {
        "stcss": { "dts": true, "extension": "stcss" }
    },
    "projects": {
        "lib": "stcss"
    },
}

• Usage in projects with override

{
    "presets": {
        "stcss": { "dts": true, "extension": "stcss" }
    },
    "projects": {
        "lib": {
        	"preset": "stcss",
		"options": {
			"dts": false
		}
	}
    }
}

Options resolution order

- default options
- config file
  - root options
  - presets
  - project override
- cli args override

Tasks:

• - parse stylable config file. (bde9849)
• - handle multilpe dependencies and build them by topological sort.
• - support watch for multiple depenedencies.
• - handle presets.
• - support watch for multiple presets.
• - add to documentaion.

Tags

#tooling

Related issues

#1813 #2001

Dependencies

• Project templates and examples #2001

[tzachbon]

Edit: moved content to top