search

nextcloud / standards

1 stars 0 forks source link

Single repository for app and related npm package #8

Open skjnldsv opened 1 year ago

skjnldsv commented 1 year ago

Single repository for app and related npm package

This decision have been taken after the following discussion: https://github.com/nextcloud/standards/issues/3

Initial idea

Sometimes it may be useful to provide an npm package to ease the integration with an existing app or to provide reusable code.

For example text markdown rendering is reused in collectives and might be useful to other apps.

Splitting the text app into a package and the app would create extra overhead in particular for backporting fixes - but also in terms of testing, issue tracking etc. - we'd probably end up with a nextcloud/text repo and a nextcloud/nextcloud-text repo. Sounds confusing and might be asking for trouble.

So instead we'd like to build the @nextcloud/text npm package from the source code of the text app. This adds a new build target. In our case it also adds some tooling because we want to build esm packages - but it's far less intrusive than splitting the app in two repos.

The package.json file so far does not contain the fields relevant to packaging ('files', 'main', 'module', 'type') etc. We added them and we have a working prototype here: https://github.com/nextcloud/text/pull/2386 So far it builds the package nicely and we can use it in collectives.

There's a bunch of metadata that is used both by the package and the app:

  • name in package.json
  • Version number in package.json
  • dependencies in package.json
  • Readme.md

Drawbacks

Seeing the issues with https://github.com/nextcloud/text/pull/2614, it's a bad idea to have them both in the same root.

  1. A package.json is representing a single element.
  2. Having both the app AND the package is actually going to mess with the dependencies and make things messy in my opinion.

We took the decision to not share package.json

Recommendations:

  1. Do not serve multiple ressources from the same package.json
  2. you can have related apps and package in the same repo
  3. Make sure we have two separate packages for those use cases. Here is an example on how it could look like: 
    MyApp/
├─ node_modules/
├─ dist/
│  ├─ myapp.esm.js
│  ├─ myapp.cjs.js
│  └─ myapp.js
├─ js/
│  └─ myapp-main.js
├─ src/
│  ├─ package/
│  │  ├─ node_modules/
│  │  ├─ lib/
│  │  │  └─ index.js
│  │  └─ package.json
│  └─ main.js
├─ package.json
│