diff --git a/docs/source/addons/i18n.md b/docs/source/addons/i18n.md index 4ae542e544..9df832da70 100644 --- a/docs/source/addons/i18n.md +++ b/docs/source/addons/i18n.md @@ -23,10 +23,10 @@ Your add-on has a `locales` folder with a `.pot` file. └── volto.po ``` -1. Run `yarn i18n` in the context of your add-on. +1. Run `pnpm i18n` in the context of your add-on. 1. Go to each `.po` file in your `locales` folder, and write the translations for each translation literal. -In the context of your project, run `yarn i18n` to merge the add-on translations with the ones of your project. +In the context of your project, run `pnpm i18n` to merge the add-on translations with the ones of your project. ## Override translations @@ -34,4 +34,4 @@ In the context of your project, run `yarn i18n` to merge the add-on translations If you have multiple add-ons installed in your project, the translations are loaded in the order your add-ons are listed in `package.json`. If two add-ons provide different translations for the same message, then the last defined add-on wins. -When running `yarn i18n` in the context of your project, the project's own locales are processed last and can override translations from any add-on. +When running `pnpm i18n` in the context of your project, the project's own locales are processed last and can override translations from any add-on. diff --git a/docs/source/addons/theme.md b/docs/source/addons/theme.md index d14d559140..99251fd370 100644 --- a/docs/source/addons/theme.md +++ b/docs/source/addons/theme.md @@ -33,7 +33,7 @@ or add a key in your `package.json` project: or via a `THEME` variable: ```shell -THEME='volto-my-theme' yarn start +THEME='volto-my-theme' pnpm start ``` 2. Create a directory `src/theme` in your add-on, then add this file `theme.config`, replacing `` with your add-on name: diff --git a/docs/source/client/quick-start.md b/docs/source/client/quick-start.md index dd3174a9b7..ad62cd181f 100644 --- a/docs/source/client/quick-start.md +++ b/docs/source/client/quick-start.md @@ -21,9 +21,11 @@ These functions can be used in other use cases like command line helpers, script To install the Javascript Plone client run the following command: ```shell -yarn add @plone/client +pnpm add @plone/client ``` +or use your package manager of choice. + ## `ploneClient` entry point The main artifact that the client provides is the `ploneClient` entry point. diff --git a/docs/source/configuration/environmentvariables.md b/docs/source/configuration/environmentvariables.md index a63c6144f1..701ce5c7c2 100644 --- a/docs/source/configuration/environmentvariables.md +++ b/docs/source/configuration/environmentvariables.md @@ -21,7 +21,7 @@ All configurable environment variables work at runtime, not only at build time. You could, for example, build your Volto application, then start it in production with the `RAZZLE_API_PATH` environment variable. ```shell -yarn build && RAZZLE_API_PATH=https://plone.org yarn start:prod +pnpm build && RAZZLE_API_PATH=https://plone.org pnpm start:prod ``` This brings you a lot of power since you don't have to rebuild on every configuration change. @@ -40,7 +40,7 @@ You can also generate builds on your continuous integration, then deploy them an However, if you are not able to upgrade the packages `plone.restapi` (8.12.1 or greater) and `plone.rest` (2.0.0a1 or greater) in the backend, you can adjust your web server configuration and use the `RAZZLE_LEGACY_TRAVERSE` flag. ```shell - RAZZLE_LEGACY_TRAVERSE=true yarn start:prod + RAZZLE_LEGACY_TRAVERSE=true pnpm start:prod ``` `VOLTO_ROBOTSTXT` @@ -50,7 +50,7 @@ You can also generate builds on your continuous integration, then deploy them an ```shell VOLTO_ROBOTSTXT="User-agent: * - Disallow: /" yarn start + Disallow: /" pnpm start ``` ```{note} @@ -67,19 +67,19 @@ You can also generate builds on your continuous integration, then deploy them an It helps you identify problems with a customization that does not work as you expect. ```shell - DEBUG=volto:shadowing yarn start + DEBUG=volto:shadowing pnpm start ``` `i18n` enables the log of missing internationalization messages in the console. ```shell - DEBUG=volto:i18n yarn start + DEBUG=volto:i18n pnpm start ``` `*` enables logging everywhere it exists in Volto. ```shell - DEBUG=volto:* yarn start + DEBUG=volto:* pnpm start ``` `DEBUG_ADDONS_LOADER` @@ -107,34 +107,34 @@ You can also generate builds on your continuous integration, then deploy them an `ADDONS` can be used to temporarily add an add-on to your build for testing purposes. ```shell - yarn add volto-slate - ADDONS=volto-slate:asDefault yarn start + pnpm add @kitconcept/volto-light-theme + ADDONS=@kitconcept/volto-light-theme pnpm start ``` `ADDONS` can also be used to temporarily enable a feature or a set of customizations. ```shell # given a folder './packages/coresandbox', like in vanilla Volto - ADDONS=coresandbox:multilingualFixture yarn start + ADDONS=coresandbox:multilingualFixture pnpm start ``` If you need to specify several add-ons, separate them with a semicolon (`;`): ```shell - ADDONS="test-addon;test-addon2" yarn start + ADDONS="test-addon;test-addon2" pnpm start ``` - + You can specify profiles for installation: - + ```shell - ADDONS="test-addon:profile1;test-addon2:profile2" yarn start + ADDONS="test-addon:profile1;test-addon2:profile2" pnpm start ``` The following code snippets demonstrate how to configure add-ons. First in `package.json`: - + ```json "addons": [ "@kitconcept/volto-blocks-grid" @@ -152,8 +152,8 @@ You can also generate builds on your continuous integration, then deploy them an And finally using `ADDONS`: ```shell - yarn add volto-slate - ADDONS=volto-slate:asDefault yarn start + pnpm add volto-slate + ADDONS=volto-slate:asDefault pnpm start ``` As a result, your app will load the add-ons in the following order: @@ -165,14 +165,14 @@ You can also generate builds on your continuous integration, then deploy them an ```{important} The `ADDONS` key is a Volto specific configuration. Simply setting `ADDONS` doesn't download the JavaScript package. - This has to be covered another way, by either installing the add-on package (with `yarn add`), or loading it as a development package with `mrs-developer`. + This has to be covered another way, by either installing the add-on package (with `pnpm add`), or loading it as a development package with `mrs-developer`. ``` `BUILD_DIR` This is a runtime-only environment variable that directs the build to run Volto from a specific location, other than the default folder `build`. ```shell - yarn + pnpm install BUILD_DIR=dist node dist/server.js ``` @@ -182,7 +182,7 @@ You can also generate builds on your continuous integration, then deploy them an It can be relative to the current project or absolute. ```shell - VOLTOCONFIG=../../volto.config.js yarn start + VOLTOCONFIG=../../volto.config.js pnpm start ``` ```` diff --git a/docs/source/configuration/internalproxy.md b/docs/source/configuration/internalproxy.md index ec8612fe65..dde6c9b369 100644 --- a/docs/source/configuration/internalproxy.md +++ b/docs/source/configuration/internalproxy.md @@ -61,7 +61,7 @@ export const settings = { or use the environment variable: ```bash -RAZZLE_DEV_PROXY_API_PATH=http://localhost:8081/mysite yarn start +RAZZLE_DEV_PROXY_API_PATH=http://localhost:8081/mysite pnpm start ``` This redefines the request path from the internal proxy of the server side Node.js process to the Plone content backend API, but leaves the frontend Volto process making all content requests to `http://localhost:3000/++api++/`. diff --git a/docs/source/configuration/volto-config-js.md b/docs/source/configuration/volto-config-js.md index a8e4c4faa7..8bb16ce951 100644 --- a/docs/source/configuration/volto-config-js.md +++ b/docs/source/configuration/volto-config-js.md @@ -70,11 +70,11 @@ This environment variable allows you to specify a custom location for {file}`vol It can be relative to the current project or absolute. ```shell -VOLTOCONFIG=../../volto.config.js yarn start +VOLTOCONFIG=../../volto.config.js pnpm start ``` ```shell -VOLTOCONFIG=$(pwd)/volto.config.js yarn start +VOLTOCONFIG=$(pwd)/volto.config.js pnpm start ``` You can also set it from the root of the monorepo: diff --git a/docs/source/configuration/zero-config-builds.md b/docs/source/configuration/zero-config-builds.md index 7b4c396075..5ac09d7d87 100644 --- a/docs/source/configuration/zero-config-builds.md +++ b/docs/source/configuration/zero-config-builds.md @@ -17,7 +17,7 @@ In the past (before Volto 13), Volto was configured in build time using several environment variables, commonly supplied via the command line, such as the following: ```shell -PORT=11001 RAZZLE_API_PATH=https://plone.org/api yarn build` +PORT=11001 RAZZLE_API_PATH=https://plone.org/api pnpm build` ``` and since Razzle is an isomorphic application, some of these values passed on build time, were diff --git a/docs/source/contributing/linting.md b/docs/source/contributing/linting.md index cd291fd556..feea6f0307 100644 --- a/docs/source/contributing/linting.md +++ b/docs/source/contributing/linting.md @@ -76,7 +76,7 @@ From here we will have access to the commands to check for errors and to fix the You can run the pnpm `eslint`, `prettier`, and `stylelint` commands from the Volto package folder: ```shell -pnpm lint +pnpm lint pnpm prettier pnpm stylelint ``` @@ -89,8 +89,13 @@ pnpm prettier:fix pnpm stylelint:fix ``` -````{note} -The same commands can be found in your Volto add-on projects, as seen in the [`package.json.tpl`](https://github.com/plone/volto/blob/main/packages/generator-volto/generators/app/templates/package.json.tpl#L10) file. +```{versionadded} Volto 18.0.0-alpha.43 +[Cookieplone](https://github.com/plone/cookieplone) is now the recommended way to develop Volto projects, using it as a boilerplate generator. +Cookieplone uses the frontend code installed using `pnpm` instead of `yarn`. +``` + +````{deprecated} Volto 18.0.0 +The same commands can be found in your Volto legacy add-ons and projects created with `@plone/generator-volto`, as seen in the [`package.json.tpl`](https://github.com/plone/volto/blob/main/packages/generator-volto/generators/app/templates/package.json.tpl#L10) file. You will use similar commands to run the linting commands, but with `yarn` instead of `pnpm`: diff --git a/docs/source/contributing/testing.md b/docs/source/contributing/testing.md index a1244c9496..37f241151d 100644 --- a/docs/source/contributing/testing.md +++ b/docs/source/contributing/testing.md @@ -66,10 +66,9 @@ This makes it faster and easier to test code changes. In GitHub workflows or for testing add-ons, it's useful to use an alternate Jest configuration. Volto provides a way to do so using a file {file}`jest.config.js`, or pointing the test runner to a file of your choice, using the `RAZZLE_JEST_CONFIG` environment variable. -Because the Volto add-ons and Volto add-ons projects still use `yarn`, you must run the test command using `yarn` instead of `pnpm`. ```shell -RAZZLE_JEST_CONFIG=my-custom-jest-config.js yarn test +RAZZLE_JEST_CONFIG=my-custom-jest-config.js pnpm test ``` ```{note} @@ -85,7 +84,7 @@ Sometimes you need to enable different configurations and enable optional compon You can use the `ADDONS` environment variable to define them. ```bash -ADDONS=test-addon,test-addon2 yarn start +ADDONS=test-addon,test-addon2 pnpm start ``` See {doc}`../configuration/environmentvariables` for more information. diff --git a/docs/source/deploying/seamless-mode.md b/docs/source/deploying/seamless-mode.md index a678728a73..0173bdbaf3 100644 --- a/docs/source/deploying/seamless-mode.md +++ b/docs/source/deploying/seamless-mode.md @@ -48,13 +48,13 @@ All the environment variables that are configurable now work at runtime, not at Before Volto 13, you'd do: ```bash -RAZZLE_API_PATH=https://plone.org yarn build && yarn start:prod +RAZZLE_API_PATH=https://plone.org pnpm build && pnpm start:prod ``` From Volto 13 onwards, you can now do: ```bash -yarn build && RAZZLE_API_PATH=https://plone.org yarn start:prod +pnpm build && RAZZLE_API_PATH=https://plone.org pnpm start:prod ``` ```` @@ -130,7 +130,7 @@ server { error_log /dev/stdout; # [seamless mode] Recommended as default configuration, using seamless mode new plone.rest traversal - # yarn build && yarn start:prod + # pnpm build && pnpm start:prod location ~ /\+\+api\+\+($|/.*) { rewrite ^/\+\+api\+\+($|/.*) /VirtualHostBase/http/myservername.org/Plone/++api++/VirtualHostRoot/$1 break; proxy_pass http://backend; @@ -138,7 +138,7 @@ server { # Legacy deployment example, using RAZZLE_LEGACY_TRAVERSE Volto won't append ++api++ automatically # Recommended only if you can't upgrade to latest `plone.restapi` and `plone.rest` - # yarn build && RAZZLE_API_PATH=http://myservername.org/api RAZZLE_LEGACY_TRAVERSE=true yarn start:prod + # pnpm build && RAZZLE_API_PATH=http://myservername.org/api RAZZLE_LEGACY_TRAVERSE=true pnpm start:prod # location ~ /api($|/.*) { # rewrite ^/api($|/.*) /VirtualHostBase/http/myservername.org/Plone/VirtualHostRoot/_vh_api$1 break; # proxy_pass http://backend; diff --git a/docs/source/deploying/sentry.md b/docs/source/deploying/sentry.md index f92ba34ecc..4266ffd4b8 100644 --- a/docs/source/deploying/sentry.md +++ b/docs/source/deploying/sentry.md @@ -82,7 +82,7 @@ SENTRY_AUTH_TOKEN=foo \ SENTRY_ORG=my_organization \ SENTRY_PROJECT=new_project \ SENTRY_RELEASE=2.0.0 \ -SENTRY_DSN=https://boo@sentry.com/1 yarn build +SENTRY_DSN=https://boo@sentry.com/1 pnpm build node build/server.js ``` @@ -265,7 +265,7 @@ SENTRY_PROJECT=new_project SENTRY_RELEASE=2.0.0 SENTRY_DSN=https://boo@sentry.com/1 SENTRY_FRONTEND_CONFIG='{"tags":{"site":"www.test.com","app":"test_app"},"extras":{"logger":"javascript-frontend", "release":"1.4.1"}}' -SENTRY_BACKEND_CONFIG='{"tags":{"site":"www.test.com","app":"test_app"} yarn build +SENTRY_BACKEND_CONFIG='{"tags":{"site":"www.test.com","app":"test_app"} pnpm build node build/server.js ``` diff --git a/docs/source/deploying/simple.md b/docs/source/deploying/simple.md index 1215cb3cd5..31b3894a3e 100644 --- a/docs/source/deploying/simple.md +++ b/docs/source/deploying/simple.md @@ -12,7 +12,7 @@ myst: Volto is a Node.js application that runs on your machine/server and listens to a port. Once you are ready to deploy it, you should build it running: ```bash -$ yarn build +$ pnpm build ``` The Volto configuration determines the external URL Volto will be served, so if you just issue this command, the build will get that values and build an static bundle with that values (PORT=3000, API_PATH=http://localhost:8080/Plone). @@ -20,13 +20,13 @@ The Volto configuration determines the external URL Volto will be served, so if In order to make Volto work on a server under an specific DNS name, you must parametrize the build like: ```bash -$ PORT=volto_node_process_port RAZZLE_API_PATH=https://mywebsite.com/api yarn build +$ PORT=volto_node_process_port RAZZLE_API_PATH=https://mywebsite.com/api pnpm build ``` After the build, the bundle is created in `/build` folder, then in order to launch your application you can run: ```bash -$ yarn start:prod +$ pnpm start:prod ``` or ```bash diff --git a/docs/source/development/creating-project.md b/docs/source/development/creating-project.md index 5052533f81..f5ef93fefc 100644 --- a/docs/source/development/creating-project.md +++ b/docs/source/development/creating-project.md @@ -9,60 +9,15 @@ myst: # Create a Volto project without a backend -This document shows how to create a Volto project with the frontend only when you have your own existing backend, such as Plone {term}`Classic UI`, {term}`Nick`, or {term}`Guillotina`. +```{versionadded} Volto 18.0.0-alpha.43 +``` + +[Cookieplone](https://github.com/plone/cookieplone) is now the recommended way to develop Volto projects, using it as a boilerplate generator. +Even if you don't need the backend, you can create a Plone project, then use only the {file}`frontend` folder for your purposes. +As a bonus, it will contain the means for deploying your project. ```{seealso} To create a full Plone project with both frontend and backend, see {doc}`plone:install/create-project` instead. To contribute to Volto, see {doc}`../contributing/developing-core`. ``` - -For using Volto for a project—in other words, use Volto as a library—you should use Volto's project generator `@plone/generator-volto`. -It's a boilerplate project generator based on Yeoman that will provide you with the basic files and folder structure to bootstrap a Volto site. -In addition to bootstrapping stand-alone Volto projects, it can also bootstrap Volto add-ons. - -1. Open a terminal and execute: - - ```shell - npm install -g yo @plone/generator-volto - # Install the latest and stable release of Volto with the following command - yo @plone/volto - # or you can install the "canary" release, including any alpha release - yo @plone/volto --canary - # or you can install any specific released version - yo @plone/volto --volto=15.0.0 - # you can even pass a GitHub repo and specific branch - yo @plone/volto --volto=plone/volto#16.0.0 - # you can bootstrap with add-ons - yo @plone/volto --addon=volto-form-block - ``` - -2. Answer the questions when prompted, and provide the name of the new app (folder) to be created. - For the sake of this documentation, use `myvoltoproject` as the project name. - - ````{note} - You can run the generator with parameters to tailor your requirements. - - ```shell - yo @plone/volto --help - ``` - - ```{seealso} - [`@plone/generator-volto` `README.md`](https://github.com/plone/volto/blob/main/packages/generator-volto/README.md). - ``` - ```` - -3. Change your working directory to the newly created folder `myvoltoproject` (or whatever name you entered). - - ```shell - cd myvoltoproject - ``` - -4. `@plone/generator-volto` installed the dependencies for you. - Start the project. - - ```shell - yarn start - ``` - - This starts the development server, which compiles the project code, and when done, it serves the app at http://localhost:3000. diff --git a/docs/source/development/environment-variables.md b/docs/source/development/environment-variables.md index 6b8b79efc3..78dc734177 100644 --- a/docs/source/development/environment-variables.md +++ b/docs/source/development/environment-variables.md @@ -33,7 +33,7 @@ docker run -it --rm -p 55001:8080 -e SITE=Plone -e ADDONS='plone.restapi==8.20.0 ``` ```shell -RAZZLE_DEV_PROXY_API_PATH='http://localhost:55001/Plone' yarn start +RAZZLE_DEV_PROXY_API_PATH='http://localhost:55001/Plone' pnpm start ``` Let's say that you do have it in a customized site id: http://localhost:55001/myplonesite @@ -43,7 +43,7 @@ docker run -it --rm -p 55001:8080 -e SITE=myplonesite -e ADDONS='plone.restapi== ``` ```shell -RAZZLE_DEV_PROXY_API_PATH='http://localhost:55001/myplonesite' yarn start +RAZZLE_DEV_PROXY_API_PATH='http://localhost:55001/myplonesite' pnpm start ``` ### Debug an external site (provided you have access to it) @@ -55,7 +55,7 @@ This is an advanced feature, and needs understanding of what you are doing and w Let's say you want to debug a deployed site in production, but the build does not allow you to look deeper into the tracebacks. You could bootstrap a frontend in your machine, and point it to the production server, combining environment variables like: ``` -RAZZLE_DEV_PROXY_API_PATH=https://2021.ploneconf.org RAZZLE_PROXY_REWRITE_TARGET=https://2021.ploneconf.org/++api++ yarn start +RAZZLE_DEV_PROXY_API_PATH=https://2021.ploneconf.org RAZZLE_PROXY_REWRITE_TARGET=https://2021.ploneconf.org/++api++ pnpm start ``` This has the drawback that could be that the proxy does not work well with the proxied SSL connection. @@ -63,7 +63,7 @@ This has the drawback that could be that the proxy does not work well with the p If you have access (via tunnel) to the port of the deployed backend is even more easier: ``` -RAZZLE_DEV_PROXY_API_PATH=http://2021.ploneconf.org:8080/Plone yarn start +RAZZLE_DEV_PROXY_API_PATH=http://2021.ploneconf.org:8080/Plone pnpm start ``` This will use the internal proxy to access the backend, bypassing CORS. diff --git a/docs/source/development/i18n.md b/docs/source/development/i18n.md index 36bffe4dfc..f9f2f4dd03 100644 --- a/docs/source/development/i18n.md +++ b/docs/source/development/i18n.md @@ -145,7 +145,7 @@ Volto provides an i18n extraction script to get all translatable strings from yo You can invoke this script with the following command. ```sh -yarn i18n +pnpm i18n ``` This will generate the following output: @@ -181,7 +181,7 @@ defineMessages({ }); ``` -Then run `yarn i18n`. +Then run `pnpm i18n`. You will find the translation ready to override in your `locales` directory, such as `locales/de/LC_MESSAGES/volto.po`. ```text @@ -190,7 +190,7 @@ msgid "Back" msgstr "My overridden translation" ``` -After you set the override, then run `yarn i18n` again to create the `de.json` translation files. +After you set the override, then run `pnpm i18n` again to create the `de.json` translation files. Restart Volto to see the changes applied. diff --git a/docs/source/development/ie11compat.md b/docs/source/development/ie11compat.md deleted file mode 100644 index 16735ed7ae..0000000000 --- a/docs/source/development/ie11compat.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -myst: - html_meta: - "description": "Legacy browser support with polyfills, babel-env, and pre- and post-transpiling" - "property=og:description": "Legacy browser support with polyfills, babel-env, and pre- and post-transpiling" - "property=og:title": "Legacy Browser Support (IE11 compatibility)" - "keywords": "Volto, Plone, frontend, React, IE11 compatibility, polyfills, legacy browser support" ---- - -# Legacy Browser Support (IE11 compatibility) - -There are some caveats if we still want to target IE11 as supported browser. - -```{important} -This documentation is orientative. Volto does NOT support legacy or vendor deprecated browsers (as in IE11). -``` - -## Version pinning - -These package versions should be pinned to this especific versions, unless -their code or dependencies have some es6 only compatible, because their -maintainers mainly target the Node.js world. - -* "query-string": "4.1.0" -* "superagent": "3.8.2" - -## Polyfills - -Then in the project that should target it, these changes are required: - -add as a dependency `@babel/polyfill`. - - yarn add @babel/polyfill - -and in `src/client.jsx`: - -```js -import '@babel/polyfill'; -``` - -```{seealso} -See https://babeljs.io/docs/babel-polyfill for more updated information -``` - -## babel-env - -Razzle supports `@babel/preset-env`, that supports including `browserlist` in -`package.json`. So you can add this to `package.json`: - -```json - "browserslist": [ - "last 2 version", - "IE 11" - ], -``` - -This supports the query specific DSL for `browserlist` targeting the browsers -that you need to add. - -## Pre-transpiling - -Some packages in `node_modules` are ES6 only, for some older browsers, you might want to add a pre (or post) transpiling. There's a script `pre-build-transpiling.js` (Volto root folder) that might help you with it. Also this command line might help: - - ./node_modules/.bin/babel --presets="@babel/env" XXX --out-dir XXX diff --git a/docs/source/development/index.md b/docs/source/development/index.md index 90c28191f8..a1e5952999 100644 --- a/docs/source/development/index.md +++ b/docs/source/development/index.md @@ -36,5 +36,4 @@ pluggables widget how-to-restrict-blocks color-picker-widget -ie11compat ``` diff --git a/docs/source/development/lazyload.md b/docs/source/development/lazyload.md index 668a7190b8..7a04d373cf 100644 --- a/docs/source/development/lazyload.md +++ b/docs/source/development/lazyload.md @@ -36,7 +36,7 @@ You can find the complete `@loadable/component` documentation here: https://load You can check the code splitting state by using the included bundle analyzer: ```shell -yarn analyze +pnpm --filter=volto analyze ``` A browser will open with the bundle inspector. diff --git a/packages/volto/news/6433.documentation b/packages/volto/news/6433.documentation new file mode 100644 index 0000000000..82111de185 --- /dev/null +++ b/packages/volto/news/6433.documentation @@ -0,0 +1 @@ +Replace `yarn` with `pnpm` wherever necessary. @sneridagh