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

Update @plone/* packages info #6521

Merged
merged 3 commits into from
Dec 8, 2024
Merged

Update @plone/* packages info #6521

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1c3a7d2
Update @plone/* packages info
sneridagh Dec 8, 2024
431c991
Apply suggestions from code review
sneridagh Dec 8, 2024
6f3ba7d
Remove non-existing yet packages
sneridagh Dec 8, 2024
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
45 changes: 34 additions & 11 deletions PACKAGES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,37 @@

This document describes the packages that come with Volto, the default frontend for Plone 6.

These packages are part of Plone's API-first story.
Most of them are experimental and are marked in their respective `README` files.
Plone 6.1 (Volto 18) depends on:
sneridagh marked this conversation as resolved.
Show resolved Hide resolved
- `@plone/registry`
- `@plone/scripts`
- `@plone/volto-slate`

and as a development dependency:
- `@plone/types`

Plone 6 (Volto 17 and below) does not use any of them.
sneridagh marked this conversation as resolved.
Show resolved Hide resolved

These packages are expected to be used and part of Plone 7.
sneridagh marked this conversation as resolved.
Show resolved Hide resolved
Could be that some of them will be part of the upcoming Plone minor versions prior to Plone 7.
sneridagh marked this conversation as resolved.
Show resolved Hide resolved

The packages are divided in three categories or types:
sneridagh marked this conversation as resolved.
Show resolved Hide resolved

- core
- utilities
- add-ons


## `@plone/types`

Plone types is a special development package.
It contains the Plone typings for TypeScript.
It's considered a core package, and it's the only package that the other core packages can rely on as
a `devDependency` in your project configuration.
It's considered a core package, and it's the only package that the other core packages can rely on as a `devDependency` in your project configuration.

This package contains `.d.ts` typing definitions, curated by hand.
Due to the nature of this package, it does not need bundling.
It's published "as is", so you can import the type definitions from anywhere in your code.
Due to the nature of this package, it does not need to be built nor bundled.
It is published "as is", so you can import the type definitions from anywhere in your code.


## Core packages
Expand All @@ -29,11 +49,11 @@ They must be published and bundled in a traditional (transpiled) way.
The bundle of these packages must work on both CommonJS and ECMAScript Module (ESM) environments.


## Utility packages
## Utilities packages

- `@plone/drivers`
- `@plone/helpers`
- `@plone/providers`
- `@plone/helpers`
- `@plone/drivers`
Copy link
Collaborator

Choose a reason for hiding this comment

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

Can you leave these sorted alphabetically?

Copy link
Member Author

Choose a reason for hiding this comment

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

I've ordered by relevance to me, due to the current state of things (drivers and rsc are not a thing yet). It just occurred to me that if they do not exist yet, let's remove them.

- `@plone/rsc`


Expand All @@ -44,19 +64,22 @@ They must be published in the traditional way, as a bundle.
This bundle must work on both CommonJS and ESM environments.


## Feature packages
## Add-on packages

- `@plone/blocks`
- `@plone/contents`
- `@plone/slots`
- `@plone/theming`
- `@plone/contents`
Copy link
Collaborator

Choose a reason for hiding this comment

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

Can you leave these sorted alphabetically?

Copy link
Member Author

Choose a reason for hiding this comment

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

Same as above, but if you think it's valuable, let's do it.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Yeah, relevance is arbitrary to the developer. Alpha also makes it easier to find in a list.



### Rules

Feature packages, or add-on packages, can depend on any other package.
Add-on or feature packages, can depend on any other package.
You must distribute them as source code, and not transpile them.
They must provide a default configuration registry loader as the default main entry point export.
They must be loadable as any other add-on.
Unlike Volto add-ons, it is preferibly *NOT* to place the code in `src` folder.
sneridagh marked this conversation as resolved.
Show resolved Hide resolved
If the package is not being transpiled, the direct resolution must work OOTB, so the bundlers resolution is direct, as well as the TypeScript resolution.
sneridagh marked this conversation as resolved.
Show resolved Hide resolved
They must be loadable as any other add-on and contain an add-on registry compatible `install`-able default export.
sneridagh marked this conversation as resolved.
Show resolved Hide resolved


## Development utility packages
Expand Down
Loading