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.

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

add description on creating a frontend project with cookieplone an… #1649

Closed
wants to merge 33 commits into from
Closed
Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
00f2afd
DEV: add description on creating a project with cookiecutter-volto an…
merkur Apr 12, 2024
f75a993
DEV: describe installation of nodejs
merkur Apr 12, 2024
902c2b2
DEV: improve info on install requirements and description
merkur Apr 12, 2024
43a90fe
DEV: apply suggestions from code review, improve & restructure doc
animus888 Apr 13, 2024
a842615
DEV: remove redundant description of cookiecutter command
merkur Apr 13, 2024
aa09962
DEV: add info on frontend-only support to introduction
merkur Apr 15, 2024
620b424
Merge branch '6.0' into 6.0
animus888 Apr 17, 2024
1084e89
Merge branch 'plone:6.0' into 6.0
animus888 Apr 19, 2024
a8f2e67
Merge branch 'plone:6.0' into 6.0
animus888 Apr 21, 2024
b40c191
DEV: use nvm installation include file
animus888 Apr 21, 2024
019d624
Merge branch 'plone:6.0' into 6.0
animus888 Apr 25, 2024
60f2f4a
Merge branch 'plone:6.0' into 6.0
animus888 May 2, 2024
0b7dd7d
DEV: emphasize that cookiecutter-volto only supports frontend dev
animus888 May 2, 2024
b94b9c1
Merge branch 'plone:6.0' into 6.0
animus888 May 3, 2024
1398f6e
Merge branch 'plone:6.0' into 6.0
animus888 May 16, 2024
e57b1ab
DEV: switch to cookieplone
animus888 May 16, 2024
21d50ac
Merge branch 'plone:6.0' into 6.0
animus888 May 21, 2024
99aaab1
Merge branch 'plone:6.0' into 6.0
animus888 May 23, 2024
6deff12
Merge branch 'plone:6.0' into 6.0
animus888 Jun 3, 2024
789fba0
Merge branch 'plone:6.0' into 6.0
animus888 Jun 11, 2024
d50dc20
Merge branch 'plone:6.0' into 6.0
animus888 Jun 17, 2024
3088131
Merge branch 'plone:6.0' into 6.0
animus888 Jun 19, 2024
41983a6
Merge branch 'plone:6.0' into 6.0
animus888 Jul 2, 2024
2690bb3
DEV: hint on activating pnpm with corepack
animus888 Jul 2, 2024
5ba7623
DEV: add info on using specific pnpm version
animus888 Jul 3, 2024
c85e1d4
STY: improve new part with line breaks
animus888 Jul 3, 2024
2928f68
Merge branch 'plone:6.0' into 6.0
animus888 Jul 8, 2024
4be4592
Merge branch 'plone:6.0' into 6.0
animus888 Jul 15, 2024
1dff68e
Merge branch 'plone:6.0' into 6.0
animus888 Jul 24, 2024
f5f0a6b
Merge branch 'plone:6.0' into 6.0
animus888 Jul 31, 2024
bd547b8
Merge branch 'plone:6.0' into 6.0
animus888 Aug 5, 2024
c8f095f
Merge branch 'plone:6.0' into 6.0
animus888 Aug 26, 2024
5982a31
Merge branch 'plone:6.0' into 6.0
animus888 Sep 24, 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
183 changes: 183 additions & 0 deletions docs/install/create-project-cookiecutter-volto.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,183 @@
---
myst:
html_meta:
"description": "Create a project with cookiecutter-volto (experimental)"
"property=og:description": "Create a project with cookiecutter-volto (experimental)"
"property=og:title": "Create a project with cookiecutter-volto (experimental)"
"keywords": "Plone, Plone 6, create, project, install, cookiecutter-volto, pnpm"
---

(create-a-project-with-cookiecutter-volto-experimental-label)=

# Create a project with cookiecutter-volto (experimental)
animus888 marked this conversation as resolved.
Show resolved Hide resolved

This chapter describes the usage of the currently experimental {term}`cookiecutter` project [plone/cookiecutter-volto](https://github.com/plone/cookiecutter-volto/).
animus888 marked this conversation as resolved.
Show resolved Hide resolved
The development of this add-on is done in isolation using a new approach using {term}`pnpm` workspaces and latest {term}`mrs-developer` and other Volto core improvements.
animus888 marked this conversation as resolved.
Show resolved Hide resolved
In order to get started you will need {term}`pipx`, {term}`Make`, {term}`Node.js` and {term}`Docker` see {ref}`create-a-project-with-cookiecutter-volto-experimental-installation-label` section below.
animus888 marked this conversation as resolved.
Show resolved Hide resolved

After that you can run following command to create your project:
```shell
pipx run cookiecutter gh:plone/cookiecutter-volto
```
animus888 marked this conversation as resolved.
Show resolved Hide resolved

(create-a-project-with-cookiecutter-volto-experimental-installation-label)=
animus888 marked this conversation as resolved.
Show resolved Hide resolved

## Installation
animus888 marked this conversation as resolved.
Show resolved Hide resolved

(create-a-project-with-cookiecutter-volto-experimental-installation-pipx-label)=

### pipx

Install {term}`pipx`.
animus888 marked this conversation as resolved.
Show resolved Hide resolved

```shell
pip install pipx
```

(create-a-project-with-cookiecutter-volto-experimental-installation-gnu-make-label)=

### GNU make

```{include} ../volto/contributing/install-make.md
```

(create-a-project-with-cookiecutter-volto-experimental-installation-node.js-label)=
animus888 marked this conversation as resolved.
Show resolved Hide resolved

### Node.js
animus888 marked this conversation as resolved.
Show resolved Hide resolved

First you'll need nvm, {term}`Node Version Manager`.
animus888 marked this conversation as resolved.
Show resolved Hide resolved

#### nvm
animus888 marked this conversation as resolved.
Show resolved Hide resolved

The following terminal session commands use `bash` for the shell.
Adapt them for your flavor of shell.

```{seealso}
See the [`nvm` install and update script documentation](https://github.com/nvm-sh/nvm#install--update-script).
For the `fish` shell, see [`nvm.fish`](https://github.com/jorgebucaran/nvm.fish).
```

1. Create your shell profile, if it does not exist.

```shell
touch ~/.bash_profile
```

2. Download and run the `nvm` install and update script, and pipe it into `bash`.

```shell
curl -o- https://raw.githubusercontent.com/creationix/nvm/v{NVM_VERSION}/install.sh | bash
```

3. Source your profile.
Alternatively close the session and open a new one.

```shell
source ~/.bash_profile
```

4. Verify that the `nvm` version is that which you just installed or updated:

```shell
nvm --version
```
animus888 marked this conversation as resolved.
Show resolved Hide resolved
#### Finally install Node.js
animus888 marked this conversation as resolved.
Show resolved Hide resolved

```{include} ../volto/contributing/install-nodejs.md
```

animus888 marked this conversation as resolved.
Show resolved Hide resolved
(create-a-project-with-cookiecutter-volto-experimental-installation-docker-label)=

### Docker

{term}`Docker` is needed later to start the plone backend inside a container.

```{include} ../volto/contributing/install-docker.md
```


(project-add-ons-label)=
animus888 marked this conversation as resolved.
Show resolved Hide resolved

# Project Add-Ons
animus888 marked this conversation as resolved.
Show resolved Hide resolved

After having initially built frontend and backend using the command `make install`,
animus888 marked this conversation as resolved.
Show resolved Hide resolved
animus888 marked this conversation as resolved.
Show resolved Hide resolved
you will have the configuration file {file}`volto.config.js` (and other stuff) inside your top add-on folder:
animus888 marked this conversation as resolved.
Show resolved Hide resolved
```js
const addons = ['youraddon'];
const theme = '';

module.exports = {
addons,
theme,
};
```

In {file}`volto.config.js` you can add add-ons like this:
animus888 marked this conversation as resolved.
Show resolved Hide resolved
```js
const addons = ['youraddon','@kitconcept/volto-light-theme'];
```

You also have to add it to the `dependencies` section of {file}`packages/youraddon/package.json`:
animus888 marked this conversation as resolved.
Show resolved Hide resolved
```json
"dependencies": {
"@plone/components": "1.7.0",
"@kitconcept/volto-light-theme" : "^3.2"
},
```

If your desired add-on is a theme addon, you should also change following line in {file}`volto.config.js`:
animus888 marked this conversation as resolved.
Show resolved Hide resolved
```js
const theme = '@kitconcept/volto-light-theme';
```

After all that, you have to execute `make install` again in order to install the new add-on.
animus888 marked this conversation as resolved.
Show resolved Hide resolved

(start-frontend-and-backend)=

# Start frontend and backend
animus888 marked this conversation as resolved.
Show resolved Hide resolved
Now you are ready to run your project.
You can start frontend and backend in separate terminal sessions in the same project directory:
animus888 marked this conversation as resolved.
Show resolved Hide resolved

```shell
make start-backend-docker
```

```shell
pnpm start
```

(change-the-logo-label)=

## Change the Logo

You can change the logo locally or by overriding Logo component of an installed theme add-on e.g. `kitconcept/volto-light-theme`.
animus888 marked this conversation as resolved.
Show resolved Hide resolved

`````{tab-set}
````{tab-item} local
In order to override the Logo component, you will have to add following file:
animus888 marked this conversation as resolved.
Show resolved Hide resolved
{file}`packages/youraddon/src/customizations/components/Logo/Logo.jsx`
animus888 marked this conversation as resolved.
Show resolved Hide resolved

Then you only have to change the line where the logo gets imported to:
animus888 marked this conversation as resolved.
Show resolved Hide resolved
```js
import LogoImage from '../../../../../images/Logo.svg';
```

Assuming you got your Logo ready in an local images folder like {file}`packages/youraddon/src/images/Logo.svg`
animus888 marked this conversation as resolved.
Show resolved Hide resolved
````

````{tab-item} volto-light-theme
Target Add-On Component: `src/components/Logo/Logo.jsx` of `kitconcept/volto-light-theme`
animus888 marked this conversation as resolved.
Show resolved Hide resolved

Of course, this only works if you have already installed the `kitconcept/volto-light-theme` add-on.

In order to override the Logo component of the volto-light-theme package, you will have to add following file:
animus888 marked this conversation as resolved.
Show resolved Hide resolved
{file}`packages/youraddon/src/customizations/@kitconcept/volto-light-theme/components/Logo/Logo.jsx`
animus888 marked this conversation as resolved.
Show resolved Hide resolved

Then you only have to change the line where the logo gets imported to:
animus888 marked this conversation as resolved.
Show resolved Hide resolved
```js
import LogoImage from '../../../../../images/Logo.svg';
```

Assuming you got your Logo ready in an local images folder like {file}`packages/youraddon/src/images/Logo.svg`
animus888 marked this conversation as resolved.
Show resolved Hide resolved
````
`````
1 change: 1 addition & 0 deletions docs/install/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@ See {doc}`plone:contributing/index`.
:hidden: true

create-project
create-project-cookiecutter-volto
manage-add-ons-packages
containers/index
```