diff --git a/.github/styles/vocab.txt b/.github/styles/vocab.txt index c3c67ab66e..28b0ec45d2 100644 --- a/.github/styles/vocab.txt +++ b/.github/styles/vocab.txt @@ -115,6 +115,7 @@ Kumar learnings lerna Lerna +Luxon magiclink mailto maintainership diff --git a/docs/architecture-decisions/adr010-luxon-date-library.md b/docs/architecture-decisions/adr010-luxon-date-library.md new file mode 100644 index 0000000000..e72a685488 --- /dev/null +++ b/docs/architecture-decisions/adr010-luxon-date-library.md @@ -0,0 +1,46 @@ +--- +id: adrs-adr010 +title: ADR010: Luxon Date Library +description: Architecture Decision Record (ADR) for Luxon Date Library +--- + +| Created | Status | +| ---------- | ------ | +| 2021-01-16 | Open | + +# ADR010: Luxon Date Library + +## Status + +Proposed + +## Context + +Date formatting (e.g. `a day ago`) and calculations are common within Backstage. +Some of these useful features are not supported by the standard JavaScript +`Date` object. The popular [Moment.js](https://momentjs.com/) library has been +commonly used to fill this gap but suffers from large bundle sizes and mutable +state issues. On top of this, `momentjs` is +[being sunset](https://momentjs.com/docs/#/-project-status/) and the project +recommends using one of the more modern alternative libraries. + +See +[[RFC] Standardized Date & Time Library](https://github.com/backstage/backstage/issues/3401) + +## Decision + +We will use [Luxon](https://moment.github.io/luxon/index.html) as the standard +date library within Backstage. + +`Luxon` provides a similar feature set and API to `Moment.js`, but improves on +it's design through immutability and the usage of modern JavaScript APIs (e.g. +`Intl`). This results in smaller bundle sizes while providing a full feature set +and avoids the need for using additional libraries for common date & time tasks. + +## Consequences + +- All core packages and plugins within Backstage should use `Luxon` for any date + manipulation or formatting that cannot be easily accomplished with the native + JavaScript `Date` object. +- Using a single date library avoids having to learn multiple library APIs +- Having a single date library will reduce bundle sizes diff --git a/microsite/sidebars.json b/microsite/sidebars.json index f5a433fc84..3bcf6b781c 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -182,7 +182,8 @@ "architecture-decisions/adrs-adr006", "architecture-decisions/adrs-adr007", "architecture-decisions/adrs-adr008", - "architecture-decisions/adrs-adr009" + "architecture-decisions/adrs-adr009", + "architecture-decisions/adrs-adr010" ], "Contribute": ["../CONTRIBUTING"], "Support": ["support/support", "support/project-structure"], diff --git a/mkdocs.yml b/mkdocs.yml index 99a96d77dc..a2cbf11b4c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -118,6 +118,7 @@ nav: - ADR007 - Use MSW for Network Request Mocking: 'architecture-decisions/adr007-use-msw-to-mock-service-requests.md' - ADR008 - Default Catalog File Name: 'architecture-decisions/adr008-default-catalog-file-name.md' - ADR009 - Entity References: 'architecture-decisions/adr009-entity-references.md' + - ADR010 - Luxon Date Library: 'architecture-decisions/adr010-luxon-date-library.md' - Contribute: '../CONTRIBUTING.md' - Support: - 'support/support.md'