Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add web component dev guide #77

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add web component dev guide #77

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions manuals/en/uportal5-manual/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ ___We welcome any assistance in migrating documentation from legacy/other source

* [API Documentation](developer/api/README.md)
* [Maven Release Process](developer/maven-release-process.md)
* [Web Component Development](developer/web-component-development.md)

## Systems Administration

Expand Down
78 changes: 78 additions & 0 deletions manuals/en/uportal5-manual/developer/web-component-development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# Web Component Development

These should be viewed as a set of 'best practice' guidelines or recommendations when developing web components geared toward the uPortal ecosystem. While web components can be built in a variety of ways, the goal is a simple and consistent approach in development, style, and deployment.

## Build Pipeline
Until the frontend is more separated from the backend, the webjar > maven > resource-server is the approach uPortal takes to host the web components for usage on the site.

LIT & Typescript (Transpiled to ES6+)
v
Linters
v
Pre-commit hooks
Comment on lines +10 to +12
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ideally pre-commit hooks would trigger the linters automatically

v
Deployed to Sonatype
v
Bundled as a webjar
v
Deployed to Maven
Comment on lines +14 to +18
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aren't Sonatype and Maven central the same?

v
Pulled into uPortal projects via the resource-server
v
Pull into an HTML page via a link from the resource-server

## Technology
To keep this document concise, please refer to the reference implementation for details / examples of the various configurations.

### NPM
https://www.npmjs.com/

The build is handled via NPM.

### Lerna
https://lerna.js.org/
https://github.com/ChristianMurphy/lerna-webjar
Comment on lines +32 to +34
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmmm, a couple thoughts on this:

  1. lerna is (largely) being replaced by native monorepo/workspace features in npm and yarn
  2. lerna or workspaces are mostly useful when there are many web components that need to be managed.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you see a value-add in keeping multiple web components bundled in the same repository? If we could go down to a single web component per repo, and then drop lerna, that'd definitely help simplify the toolset and allow web components the flexibility to be revised in isolation

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you see a value-add in keeping multiple web components bundled in the same repository?

Yes, but there are trade offs.
If the components are using the same technologies and interdependent.
Having a monorepo can help ensure we have consistency across toolchains, dependency versions, and release timing.

If the components are not using the same technologies and interdependent.
The value proposition for monorepos breaks down, and it can be more trouble than it's worth.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

makes sense. I'll note there are two flavors of build flows (npm/yarn & lerna)

Copy link
Member

@ChristianMurphy ChristianMurphy Sep 8, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lerna is for most intents and purposes deprecated, replaced by native monorepo workspace support in package managers, removing it from uPortal web components is something I hope to do sometime.
These days npm for a single repo and npm workspaces for a monorepo would be a go-to.

Yarn and pnpm could also be options, but lately they've been trending towards a new style of module loading called plug and play, which can break random modules and can be challenging to debug without fairly in depth knowledge of node js packaging conventions and module loading rules. I'd steer clear of these to keep the guide more beginner friendly.


Builds the webjar

### Lit
https://lit.dev/

Lightweight method of creating Web Components.

### Typescript
https://www.typescriptlang.org/

Type checking.
Comment on lines +43 to +46
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It may also be nice to include https://github.com/plantain-00/type-coverage#readme and encourage a minimum amount of typing (I personally prefer 100% types, but 90% could be a good baseline)


### ESLint
https://eslint.org/

Linter for Javascript.
Comment on lines +48 to +51
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ESLint starts with all rules off, and without framework specific guidance.
It would probably be good to recommend adding

{
  "root": true,
  "parser": "@typescript-eslint/parser",
  "extends": [
     "eslint:recommended",
     "plugin:prettier/recommended",
     "plugin:@typescript-eslint/recommended",
     "plugin:wc/best-practice",
     "plugin:lit/recommended"
  ]
}


### StyleLint
https://stylelint.io/

Linter for CSS.
Comment on lines +53 to +56
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stylelint will need to be


### Remark
https://github.com/remarkjs/remark-lint

Linter for markdown.
Comment on lines +58 to +61
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will also need a ruleset https://github.com/remarkjs/remark-lint#presets
I'd recommend remark-preset-lint-recommended and remark-preset-lint-consistent paired together.


### Prettier
https://prettier.io/

Consistent code format for MD, HTML, CSS, etc.

### Editor Config

Consistent code style in the IDE.
Comment on lines +68 to +70
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This feels optional with prettier, fine with keeping it though


## Reference Implementation

The following web component aims to follow these best practices:

```
TBD - build out a web component that follows these guidelines and interacts with uPortal (ideally with CRUD operations for example's sake)
```
Loading