WIP

PACKAGES.md

@@ -0,0 +1,34 @@
+# Plone frontend packages
+
+## Core packages
+
+- `@plone/registry`
+- `@plone/client`
+- `@plone/components`
+
+### Rules
+
+They can't depend on any other `@plone/*` package, with only one exception: `@plone/types`.
+They must be published in a traditional way, bundled.
+This bundle must work on both commonjs and ESM environments.
+
+## Special development packages
+
+- `@plone/types`
+
+### Rules
+
+This package contains `.d.ts` typing definitions, curated by hand.
+Due to the nature of this package, it does not need bundling.
+It's publised "as it is", so you can import the type definitions from anywhere in your code.
+
+## Utility packages
+
+- `@plone/blocks`
+- `@plone/helpers`
+- `@plone/drivers`
+- `@plone/rsc`
+
+They can depend on core packages and other utility packages.
+They must be published in a traditional way, bundled.
+This bundle must work on both commonjs and ESM environments.

packages/types/README.md

@@ -1,3 +1,37 @@
 # @plone/types
 
 Plone unified TypeScript typings.
+
+## Rules while developing this package
+
+This package contains `.d.ts` typing definitions, curated by hand.
+Due to the nature of this package, it does not need bundling.
+It's publised "as it is", so you can import the type definitions from anywhere in your code.
+
+This files are organised in the following way:
+
+- blocks (props related to blocks and blocks components)
+- config (configuration object typings)
+- content (content releated and serialization of the content objects)
+- services (typings concerning Plone RESTAPI services)
+
+## Extending existing types in this package in your projects
+
+In a project, you often need to extend the default definitions with your own, for example, when dealing with custom content types or creating new blocks.
+
+You can use TypeScript for extending the types like this:
+
+```ts
+// We extend the block types with our custom ones
+declare module '@plone/types' {
+  export interface BlocksConfigData {
+    myCustomBlock: BlockConfigBase;
+  }
+}
+```
+
+## Compatibility
+
+You can use this package from Volto 17 onwards.
+In Volto 17, you should declare it as dependency.
+In Volto 18 it is included by default.