publishing npm modules

[crguezl]

@AdrianMoraRodriguez @PSantanaGlez13

No tengo claro que sea sencillo como publicar babel ya que es un monorepo con un montón de packages.
Tenemos que hablarlo.

Por lo pronto mover el plugin a la zona de packages e ir aprendiendo como es el proceso de publicación del monorepo.

[crguezl]

@AdrianMoraRodriguez @PSantanaGlez13, @coromoto

En Babel usan Lerna para la administración del monorepo y su publicación (vean por ejemplo npx lerna publish --help y npx lerna version --help).

Me parece que una aproximación simple para la publicación podría ser crear un nuevo monorepo simplificado con sólo dos packages:

1. Nuestra versión del babel-parser: Algo como babel-parser-defaultvector, babel-parser-left-side
2. El plugin de soporte: Algo como babel-plugin-defaultvector, babel-plugin-left-side-plugin

y publicaríamos los dos paquetes.

Luego para compilar se supone que esta instalado babel oficial y nuestros paquetes y usamos el babel oficial con la opción parserOverride:

const myPlugin = require("support-plugin");
const parse = require("custom-fork-of-babel-parser-on-npm-here");

module.exports = {
  plugins: [
    {
      parserOverride(code, opts) {
        return parse(code, opts);
      },
    },
  ],
};

y en la configuración añadimos el plugin. ¿Que problemas le ven a esta aproximación? ¿Alternativas?

Algunas Referencias sobre Lerna

• Youtube video: Taming the Hydra: Managing Monorepos with Lerna
  • Repo de ejemplo: https://github.com/EmmaRamirez/taming-the-hydra
• Lerna Crash Course: https://youtu.be/WD5T-VMCTvY?si=q3wb80LuvrPaucj4
• Make a Lerna Monorepo in 2 MINS: https://youtu.be/YtnChOgCwjY?si=5WjpHOllq0XvRABs
• Setup Lerna Monorepo with Husky: https://youtu.be/_JAP9gq8hpc?si=3HtChm4TnBF8Mljp

[crguezl]

@AdrianMoraRodriguez
Se ha publicado el resumen de @PSantanaGlez13 en la sección Building and Publishing en el tutorial https://github.com/ULL-ESIT-PL/babel-learning

[PSantanaGlez13]

@crguezl @AdrianMoraRodriguez
Encontré una manera de publicarlo. Consiste en usar la opción lerna publish from-package (después de usar un make bootstrap). Si se configuran los paquetes como acceso público y se le pone un nombre único (por ejemplo @ull-esit-pl/parser-left-side), Lerna revisará el registro y verá que no existe un paquete con esa versión y lo publicará. Lo bueno de esto es que no es necesario cambiar nada de los demás paquetes de Babel, ya que al revisar la versión que tienen en el registro Lerna verá que ya existen y no los intentará publicar. Lo malo es que las versiones de cada paquete se tendrán que gestionar de una en una (o usando otro método para versionar que no sea lerna version).

Intentándolo publicar me he encontrado con este mensaje:

sombra@P:~/projects/left-side-JS/babel-tanhauhau$ yarn lerna publish from-package
yarn run v1.22.22
$ /home/sombra/projects/left-side-JS/babel-tanhauhau/node_modules/.bin/lerna publish from-package
lerna notice cli v3.19.0
lerna WARN Yarn's registry proxy is broken, replacing with public npm registry
lerna WARN If you don't have an npm token, you should exit and run `npm login`
lerna WARN Unable to determine published version, assuming "@ull-esit-pl/parser-left-side" unpublished.
lerna WARN Unable to determine published version, assuming "@ull-esit-pl/babel-plugin-left-side-plugin" unpublished.
lerna WARN Unable to determine published version, assuming "@ull-esit-pl/babel-plugin-left-side-support" unpublished.

Found 3 packages to publish:
 - @ull-esit-pl/parser-left-side => 1.0.0
 - @ull-esit-pl/babel-plugin-left-side-plugin => 1.0.0
 - @ull-esit-pl/babel-plugin-left-side-support => 1.0.0

? Are you sure you want to publish these packages? Yes
lerna info publish Publishing packages to npm...
lerna info Verifying npm credentials
lerna http fetch GET 200 https://registry.npmjs.org/-/npm/v1/user 629ms
lerna http fetch GET 200 https://registry.npmjs.org/-/org/psantanaglez13/package?format=cli 263ms
lerna WARN The logged-in user does not have any previously-published packages, skipping permission checks...
lerna info Checking two-factor auth mode
lerna http fetch GET 200 https://registry.npmjs.org/-/npm/v1/user 621ms
lerna http fetch PUT 404 https://registry.npmjs.org/@ull-esit-pl%2fbabel-plugin-left-side-support 316ms
lerna ERR! E404 Not found
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

El problema parece ser que al no estar en la organización de npm de @ULL-ESIT-PL no puedo publicar paquetes en ella. ¿Podría tener permisos para publicar en ella? Alternativamente, se puede crear otra organización, usar mi propio usuario o publicar en el registro de GitHub.

[crguezl]

@PSantanaGlez13 @AdrianMoraRodriguez

Ahora son miembros de la organización. Deberían poder publicar paquetes en la org de GitHub y en npm

[PSantanaGlez13]

@crguezl @AdrianMoraRodriguez
Actualice el tutorial de como publicar desde el fork. Puse al final un resumen de los tres pasos principales a seguir para publicar.

También descubrí porque no me funcionaba con la versión "más actualizada" de Babel el parserOverride de mi plugin. Resulta que en npmjs hay dos versiones de Babel: babel-cli y @babel/babel-cli. La primera era la que instalé la primera vez y resulta ser el paquete de la versión más actualizada de Babel, pero Babel 6. La otra opción es la de Babel 7, la versión actual de Babel. Esta vez revisé el repositorio actual de Babel (la otra vez miré desde las dependencias en node_modules, por eso llegue a las conclusiones equivocadas) y si que conservan parserOverride en @babel/babel-core (concretamente en este fichero). He probado el plugin con esta otra versión y funciona bien.

[crguezl]

@PSantanaGlez13 @AdrianMoraRodriguez @coromoto

I have doubts about where is the best way to provide the instructions about the published packages, so I have asked v0:

Question

When publishing packages from a monorepo in the GitHub registry, what is the policy of the registry about the README.md of the package?

I noticed that by default the GitHub registry uses the root README.md as the documentation.

If we write a README.md inside the package folder, will it be referenced as the README.md documentation of the package by the GitHub registry?

v0 (edited) Answer

When it comes to publishing packages from a monorepo to package registries, including the GitHub registry, the handling of README.md files can indeed be a bit tricky. Here's what I can tell you based on general practices:

1. By default, many package registries, including GitHub's, will use the root README.md of the repository as the documentation for all packages if a package-specific README.md is not explicitly specified.
2. To ensure that the correct README.md is used for each package in a monorepo, it's generally recommended to include a separate README.md file in each package's directory.
3. However, for the package-specific README.md to be recognized and used by the registry, you typically need to ensure that it's included in the published package contents.

To make sure the GitHub registry uses the package-specific README.md instead of the root one, you should:

1. Create a README.md file in the specific package directory within your monorepo.
2. Ensure that this README.md is included in the files that are published to the registry. This often involves configuring your package.json or build process to include the README.md in the package output.

It's worth noting that the exact behavior might depend on how you're publishing your packages and what tools you're using (like Changesets, Lerna, or custom scripts) .

If you're still experiencing issues with the GitHub registry not using the package-specific README.md, you might want to check your publishing configuration and ensure that the README.md is being correctly included in the published package contents.