Goal of this package is to generate all the necessary configuration files of a project. These configuration files are used:

• to generate the package.json file
• to format
• to lint (eslint, tsc, madge, dependency check...)
• to build the prod version
• to generate the documentation
• to publish the packages to npm
• to generate scripts ...

Definitions

A package is a folder that contains a package.json file.

A package that is tracked by git (and github) is called a repo.

A repo that contains source code and does not serve as a container to other packages is called a one-package repo.

Inversely, a repo that contains no source code and serves solely as container to other packages is called a monorepo. A package contained in such a monorepo is called a sub-package. The monorepo that contains it is called its parent monorepo.

Project can be split in:

• packages that contain source code called source packages: one-package repos and sub-packages
• packages that contain no source code called no source packages: top package and monorepos

Project structure

A project is a collection of repos gathered under a top package. This top package is entirely generated by the configs package. It is therefore not tracked by git (if we happen to have several projects some day, with a specific description for each project, we may consider tracking it with git). The structure of a Project is represented below:

topPackage (no source package)
│
└───package.json
└───myeffectdevs.code-workspace (vscode workspace)
└───pnpm-workspace.yaml (pnpm workspace englobing all repos and sub-packages)
└───vitest.config.ts (vitest project refering to the contained repo vitest projects)
│
└───packages
    |
    └───configs (one-package repo, source package)
    |   │
    |   └───package.json
    |   └───vitest.config.ts (local vitest settings)
    │
    └───effectlibs (monorepo, no source package)
        └───package.json
        └───vitest.config.ts (vitest project refering to the contained vitest projects)
        │
        └───packages
            |
            └───effect-lib (sub-package, source package)
            |   │
            |   └───package.json
            |   └───vitest.config.ts (local vitest settings)
            └───conversions (sub-package, source package)
            ...

The Project level has been created for two main reasons:

• before creating it, I needed to open a vscode instance at each repo level, which consumed a lot of resources
• in development, it allows me to use the local version of all available repos

It is important to note that the Project level is not visible in github context where the highest visible level is the repo level.

Opening a single instance of vscode at project level entails that tools used by vscode and its plugins for the whole project, like Typescript, vitest, eslint, prettier, ... must be installed in the top package. However, as these tools must also work in github, they must also be installed at lower levels where they are useful.

Workspaces

The top package is a pnpm workspace because:

• it simplifies installing dependencies in all packages with a simple pnpm i
• it ensures coherence of dependencies in all packages (pnpm i tries to homogenize package installation with a workspace)
• it allows defining overrides that apply in all packages of the project using the workspace protocol. These overrides make sure internal dependencies are fetched locally instead of on npm so that modification to internal packages are reflected immediately without the need for rebuilding and republishing. This makes development faster (but it does not force me to add meaningful comments at each commit). These overrides do not operate in github context where the Project level is not visible. This is intentional: when publishing a package, we want it to use the prod version of internal dependencies.

The top package is a vscode workspace. Otherwise, vscode may not systematically track all git repos.

The top package is a vitest project (formerly called workspaces).

Package structure

Source package structure

esm directory

Each code-package contains a esm directory that contains all its modules. Note that these modules can use a .js or .ts extension. If they use a .js extension, they will be linted by Typescript, but they cannot make use of the Typescript syntax. They must use js doc comments instead.

This directory contains:

• a index.ts file that must reexport anything exported in modules not located under the internal and bin subdirectories if there are some. These re-exports can be automatically generated. If there are no such modules, the index.ts file can contain the main executable of the package;
• optionally a index.tests.ts file that can re-export exports of modules located under the internal subdirectory for test-purposes only. This index.tests.ts will not be shipped in the prod version;
• optionally a bin subdirectory that contains modules that will not be exported, but that can be used as commands called directly in the node-modules directory (or installed by pnpm if they are referenced under the bin package.json key);
• optionally a internal subdirectory that contains modules used by exported modules or commands located in the bin subdirectory.

tests directory

Each source package has a tests directory that contains test modules for all its exported and non-exported modules. Test modules must import the package as if it were an external package.

examples directory

Each source package may have a examples directory that contains example modules that can in particular be used in the documentation. Example modules must import the package as if it were an external package (because this is what the user wants to see)

Other elements common to all packages (source and no source)

project.config.json

All packages except the top package must contain a project.config.json configuration file that define the parameters used for the generation of the configuration files of that package. Definition of these parameters can be found in the NoSourceBase.ts and SourceBase.ts files.

README.md

Mandatory package documentation

Usage

If no package.json exists, run pnpx jiti esm/bin/generate-config-files.ts. Otherwise, run pnpm generate--all-config-files