Openverse Frontend

This repository is the frontend UI for accessing and exploring the openly-licensed content provided by the Openverse API.

You can view the application live on WordPress.org.

Technology

The frontend app is built using Vue.js and Nuxt.js.

Local Development

Note for Windows users: Please use WSL for developing on the Openverse frontend. Several scripts, primarily support scripts, rely on a general *nix type environment. Maintaining parity for cross platform scripts proved complicated without significant duplication. If you run into issues with running the Openverse frontend in WSL please let us know by opening an issue or joining us on Slack in the #openverse room and ask for help.

We use Volta to manage our local environment tools. Please install it using the instructions on their website.

Once you have volta installed, manually install pnpm using volta. Volta does not currently officially support pnpm so this is a stop gap solution until that support is implemented:

volta install pnpm

Run the following commands in order to have the code up and running on your machine:

# Builds and serves assets with hot-reload
# Automatically invokes pnpm install and pnpm i18n
pnpm dev

Using HTTPS Locally

To enable SSL support in local development, use the pnpm dev:secure command. This requires you to have a private key and certificate in the root of the repository with the following names:

localhost+1-key.pem # The private key file
localhost+1.pem # The certificate file

The easiest way to create these files is with a local development tool called mkcert. First make sure you have mkcert installed and activated with mkcert -install. Then use mkcert to create a certificate for localhost and for the external IP address used by Nuxt's development process. That command looks like this:

mkcert localhost 192.168.50.119

Be sure to replace the IP address in the example with your own. See the next section for how to identify that IP address.

Finding your local IP address

You can find the local IP address Nuxt uses by looking at the output of nuxt dev. Look in your console for a box of configuration details that looks like this:

#  ╭───────────────────────────────────────────╮
#  │                                           │
#  │   Nuxt @ v2.15.8                          │
#  │                                           │
#  │   ▸ Environment: development              │
#  │   ▸ Rendering:   server-side              │
#  │   ▸ Target:      server                   │
#  │                                           │
#  │   Listening: http://192.168.50.119:8443/  │ # <-- Use this IP Address
#  │                                           │
#  ╰───────────────────────────────────────────╯

You will need to regenerate the certificate if this IP address changes for any reason, like by enabling a VPN or changing networks.

Choosing which API to use

You don't need to have the Openverse API running locally to be able to run the frontend application. It's configured to communicate, by default, with the production API that's already publicly available. If you need to test against changes in your local API, set the API_URL environment variable when run the development server.

API_URL=http://localhost:8000 pnpm dev

Standalone and embedded modes

The application can run in two modes. By default, it runs in embedded mode, which is loaded in an iframe on WordPress.org/openverse. It has a small header without logo and no footer. The standalone mode which has a large header with logo and a footer, can be enabled by adding ?embedded=false query parameter to the URL. For example, when running locally, you can go to http://localhost:8443?embedded=false to view the standalone application.

Running tests

Refer to the TESTING_GUIDELINES.md file for instructions on how to run tests.

localhost tunneling

If you want to make your local development server accessible to the internet (for testing or showing someone something you're working on), you can use ngrok. Follow the documentation on the ngrok site to install it and set it up. Once you have it installed, get the development server for Openverse running and in a separate window/tab, run:

# The extra parameters are required to ensure that ngrok redirects to the HTTPS version of the site
# and that the host header matches one that is accepted by the server
# (ngrok's default hostname is randomly generated and is not whitelisted).
ngrok http http://localhost:8443 -host-header="localhost:8443"

If you need to run an HTTP version (for example, if you're testing against third-party websites that do not accept the self-signed certificate generated by the dev server), run the dev server using pnpm dev and use the following command to start ngrok:

ngrok http 8443 -host-header="localhost:8443"

Frontend Components

The frontend app is composed of a number of components that are documented in our Storybook.

CSS Framework

To design our components, we use the TailwindCSS utility-first CSS framework. We have compiled a list of TailwindCSS classes that are used in the frontend app. You can view the list here.

Development Tips

If you use VS Code, you can install the Tailwind CSS IntelliSense extension to get autocomplete for TailwindCSS classes.

Docker and Openverse frontend

We do not currently support local development using Docker or docker-compose. It was supported in the past, but it was not used by the core contributors. It remained broken for many months without ever being noticed, so the assumption is that it was also not being used active community members. Local nuxt development is still easy across platforms, so maintaining a separate Docker development stack for the frontend did not make sense.

However, we do build and actively deploy the frontend using Docker images. If you wish to build the production image for yourself, run the following:

pnpm docker:build

You can also find the latest openverse-frontend images on our GitHub packages page.

You can then run using either the locally built image or the ghcr.io image from the link above:

pnpm docker:run

The app will be available at http://localhost:8443.

Note: If you are not using HTTPS locally, do not use the URL provided by Nuxt - this will cause certificate errors because it gets rerouted to HTTPS. E.g. this link will not work:

$ pnpm docker:run

> [email protected] start
> nuxt start

ℹ Sentry reporting is disabled ("disabled" option has been set) nuxt:sentry 18:22:32

   ╭─────────────────────────────────────────╮
   │                                         │
   │   Nuxt @ v2.15.8                        │
   │                                         │
   │   ▸ Environment: production             │
   │   ▸ Rendering:   server-side            │
   │   ▸ Target:      server                 │
   │                                         │
   │   Memory usage: 48.2 MB (RSS: 152 MB)   │
   │                                         │
   │   Listening: http://172.17.0.2:8443/    │   <-- Won't work unless HTTPS is set up
   │                                         │
   ╰─────────────────────────────────────────╯

Formatting and Linting

The code in this repository is formatted using prettier. If you have prettier setup in your code editor it should work out of the box; otherwise you can use the pnpm lint:fix script to format and fix lint errors in your code. Checks are run to lint your code and validate the formatting on git precommit using husky.

You will need to fix any linting issues before committing. We recommend formatting your JavaScript files on save in your text editor. You can learn how to do this in Visual Studio Code here.

File name conventions

All files and folders should be written in kebab-case, with the exception of Vue single file components. If it ends in .vue, please use PascalCase. This distinction makes our component files stand out clearly and is recommended by the Vue community.

Redirects

From	To	Status code	Setup level
/photos/_id	/image/_id	301	Nuxt server middleware

Just

If just is your preferred command runner, you can also use just run {script} to run any pnpm script and just on its own to list the available scripts (e.g. just run docker:build). Our other projects use just as their primary script runner, so this allows parity with both the API and the catalog.

Contributing

Pull requests are welcome! Feel free to join us on Slack and discuss the project with the engineers and community members on #openverse.

You are welcome to take any open issue in the tracker labeled help wanted or good first issue; there's no need to ask for permission in advance. Other issues are open for contribution as well, but may be less accessible or well defined in comparison to those that are explicitly labeled.

Acknowledgments

Openverse, previously known as CC Search, was conceived and built at Creative Commons. We thank them for their commitment to open source and openly licensed content, with particular thanks to previous team members @ryanmerkley, @janetpkr, @lizadaly, @sebworks, @pa-w, @kgodey, @annatuma, @mathemancer, @aldenstpage, @brenoferreira, and @sclachar, along with their community of volunteers.

jalajk24 / openverse-frontend Goto Github PK