Before starting to develop collage, please read the documentation about the collage features, core concepts and core api.
git clone https://github.com/SICKAG/collage.git
cd collage
npm install
Now you are ready for developing
You can start the dev server by running
npm run dev
This will start a dev server. You can then view and debug the example and integration tests defined in the sample folders of the plugins (src/core/)
You can (and should) keep the unit test running in watch mode while developing
npm run test:watch
Hint: you can keep the dev server and the unit test running at the same time
- typescript (see typescript and tsconfig.json)
- vite for serving our examples and integration tests and bundling the library (see vite and vite.config.js)
- jest for unit tests (see jest and jest.config.js)
- vuepress for building our user documentation (see vuepress and vuepress-config.mjs)
- github actions for ci/cd
- penpal for the communication between fragments and arrangements (see penpal)
The structure of the repository is as follows. In each folder, you will find a documenting markdown file explaining the details of the respective part.
collage/
|-- .github/ // github actions configurations
|-- docs/ // user documentation built with vuepress
|-- e2e/ // our e2e tests
|-- src/ // source code
| |-- core/ // core concepts of collage implemented as collage plugins
| |-- elements/ // custom elements for a convenient usage of collage
| |-- lib/ // internal library structure of collage
| | |-- api/ // collage api
Collage is build as a plugin library. Each basic feature is defined as a plugin. All default plugins are configured and bootstrapped together.
How this is done, you can read in the documentation about the internal structure of the collage library.
In short:
- all types, and everything needed to put collage and the plugins together can be found in lib.
- everything that implements functionality for the user is a plugin and can be found in core.
Every contribution is welcome, as we want to make collage a vivid community project.
At the moment we lack a system to enable plugins dynamically, so each plugin must be built and bundled with the library. We are evaluating to change that in the future, so everybody could add functionality to collage.
- create the plugin
- create a new folder in the src/core directory
- create a plugin file as ts (orient at the core plugins)
- create a samples folder for integration testing examples
- create tests
- create e2e test for the new feature
- create unit tests in the plugin folder
- create documentation
- create a documentation file as md if necessary
- add the plugin to collage
- import the plugin
- add to the plugins array
With a plugin, you are able to enhance collage by new features. For an example of a minimal plugin, please have a look at the create-context.
In short, a valid plugin needs to export the default function plugin
where it can pass an object, that uses the PluginFunctions to enhance collage by the new features (see src/types.ts>PluginFunctions and collage-plugin).
import plugin from '../../lib/collage-plugin';
export default plugin({
enhanceExpose: async () => {
console.log('I send a message everytime expose() is called');
},
});
Read further in the Core Concepts Documentation