This section describes the project structure and our development guidelines.
- Setup the project
- Project Stack
- Project Structure
- Project Scripts
- Project Conventions
- Make or update a core and utilities
- Make or update a component
- Update demo pages
-
To get started you will need Node.js version
>=20.8.1
and NPM version>=9.0.0
. -
After cloning the repo, run:
npm i
or
npm ci
to install dependencies
-
Use
npm run start
to start development server. The development server watches source file changes out of the box.
You can create prod output assets in any moment using
npm run build
Also, you can run tests and lints using
npm run test
To make sure that all checks are passed before you commit and push your changes,
please make sure that you allow husky
to set up git hooks for you.
NOTE: be aware of the prepare
step that runs build during npm i
process.
In case you need to update dependencies in the code version that is broken and
can not build successfully, use the --ignore-scripts
param:
npm i --ignore-scripts
ESL codebase is written using TypeScript and LESS CSS-preprocessor.
ESL uses the following tools to keep codebase quality
- ESLint to lint scripts
- StyleLint to lint styles
- Jest to run unit tests
- CommitLint to check commit message format
The 11ty project and webpack are used to build a static website for project representation.
The semantic-release project and GitHub actions are used to automate the release process.
ESL project consists of the following directories:
-
📁 src - library source code
- 📁 modules - library core modules and components
- 📁 draft - library core modules and components drafts (not ready for production, out of semiver and restrictions)
- 📁 esl-component - library component directory
- 📁 test - component/module tests sources
- 📄 *.test.ts - test sources should have
.test
postfix
- 📄 *.test.ts - test sources should have
- 📁 core - component/module core source files
- 📄 core.ts - component/module main file (import core parts)
- 📄 core.less - component/module main styles
- 📄 core.mixin.less - component/module main styles mixin and references only
- 📁 test - component/module tests sources
- 📁 esl-utils - library common utilities module
- 📁 category - utilities organized in groups
- 📄 all.ts - bundled esm source
- 📄 lib.ts - global object type definition and activator
- 📄 all.less - bundled source style
- 📁 polyfills - small polyfills and shims distributed with the library
- 📁 modules - library core modules and components
-
📁 site - demo site root directory
- 📁 11ty - demo site 11ty configuration files
- 📄 *.js - will be applied to 11ty config automatically
- 📄 _*.js - will not be applied to 11ty configuration
- 🔨📁 dist - demo site build output directory
- 📁 src - demo site common styles and scripts sources
- 📁 static - demo site common static assets sources
- 📁 views - demo pages templates and 11ty common templates
- 📁 _data - 11ty global data files
- 📁 _includes - 11ty templates common parts
- 📁 _layouts - 11ty pages layouts definitions
- 📁 components - ESL components articles
- 📁 examples - examples articles
- 📁 core - ESL core articles
- 🔧 .eleventy.js - main 11ty configuration file
- 🔧 tsconfig.json - TS config for demo pages scripts
- 🔧 webpack.config.js - webpack build file for demo pages
- 📁 11ty - demo site 11ty configuration files
-
📁 eslint - sub-package root for ESL ESLint plugin
-
📁 build - library common build scripts
-
📁 linting - ES Lint rule-sets
-
📁 .github - library repository configuration and documentation
-
📁 .husky - git hooks configuration
-
🔨📁 modules - library core esm build output
-
🔨📁 polyfills - library polyfills esm build output
-
🔨📁 .report - linters / test / build-tools reports
-
npm start
ornpm run start
- start demo server locally. Runs local build, watch and BrowserSync. Uses:3005
port by default. -
npm run clean
- clear output folders -
npm run build
- build project to ESM output -
npm run build-pages
- build project auto-generated GitHub Pages -
npm test
ornpm run test
- run linters and tests (silent task, used in CI/CD) -
npm run lint
- run linting -
npm run test:unit
- run all tests -
npm run test:report
- run tests and create coverage report
ESL project uses some special JS community agreements and name conventions. To fix and track such agreements the Code Conventions document was created.
TODO: Detailed guide will be added in the future based on contribution experience
TODO: Detailed guide will be added in the future based on contribution experience
The demo site is built with Eleventy - a simple static site generator.
Nunjucks and Markdown are picked as template languages.
The project is deployed to GitHub Pages using a GitHub workflow.
In case you are using JetBrains IDE (IDEA or WebStorm) you need to follow these steps:
- Add Twig Support plugin if necessary
- Go to File -> Settings -> Editor -> File Types
- Find Twig and add the custom pattern
*.njk
. Now all *.njk files are parsed as Twig, so you have support for Nunjucks.
For Visual Studio Code you can use this plugin to support syntax highlighting.