JabRefOnline

This repository contains the source of the JabRef homepage.

Servers

• Production server: www.jabref.org This server runs the last released version with data provided by the production database.
• Staging server: staging.www.jabref.org This server runs the latest version of the main branch with data provided by the production database. Usually, you do not want to target this server. Its main purpose is to test the main branch before a release.
• Test server: dev.www.jabref.org This server runs the latest version of the main branch with test data that is usually reset on redeployment. The main use of this server is for developers to test the latest version against their application without the fear to delete user data. In particular, you can log in using [email protected] / EBNPXY35TYkYXHs.
• PR previews: Every pull request is deployed to a (temporary) server, which uses the same test data as the "Test server".

Getting started

The simplest way to start is by opening this project in Gitpod.

• Install Node.js
• Install PostgreSQL
• Checkout
• Create a .env file in the root containing the connection URL for the database, e.g. DATABASE_URL="postgresql://user:password@localhost:5432/jabref?schema=public".
• Optional: Install and start Redis. Perhaps the most straightforward way to do this is via Docker: pnpm docker:redis. If you do not use this command, make sure that Redis is available through the port 6380 or, alternatively, add the configuration REDIS_PORT=<your port> to the .env file.
• Run pnpm install to install all dependencies.
• Run pnpm prisma:migrate:dev to initialize the database. You may also want to use pnpm prisma:seed to fill the database with some initial test data.

Now you can start the server by using pnpm dev.

If you use Visual Studio Code, you might also want to activate automatic tasks which would then be run whenever you open the project and run the usual commands to get you running in no time. For this, open the command palette (Shift + Cmd + P) and choose "Tasks: Manage Automatic Tasks in Folder". Then accept "Allow Automatic Tasks in Folder". Now close and re-open the workspace.

Commands

Command	Description
pnpm install	Install project dependencies and generate code.
pnpm dev	Start Nuxt server in development mode with hot reloading enabled. Listen on http://localhost:3000. The GraphQL API is then accessible at http://localhost:3000/api
pnpm test	Execute all tests. Pass -u to update all snapshots.
pnpm build	Build the nuxt.js web application for production.
pnpm start	Start the production server built by pnpm build (for testing purposes).
pnpm prisma:studio	Explore data in the database using a visual editor.
pnpm storybook	Start Storybook in your browser.

Running tests locally

To run the tests locally, it's best to start the development server by running pnpm dev. Then, in a separate terminal, set the environment variable TEST_URL to the URL of the development server (e.g., http://localhost:3000)

# Linux
export TEST_URL=http://localhost:3000
# Windows
$env:TEST_URL = "http://localhost:3000"

Then you can run the tests by executing pnpm test.

Workflow for editing the database schema

1. Prototype your new feature by making the necessary changes to schema.prisma.
2. Run pnpm prisma:push to push the changes to the local database.
3. Iterate until feature is ready.
4. Run pnpm prisma:migrate:dev to generate new migration based on the schema changes.

See Prisma documentation for more details.

UI workflow: Storybook

As the primary UI development flow, we use Storybook which allows developing UI components in isolation without the need to start the whole application. Storybook uses so-called stories. Each story represents a single visual state of a component. For each component its stories should be placed in the same directory, with the suffix .stories.ts appended. For example,

components
│   Button.vue
│   Button.stories.ts

To start developing with Storybook, simply run pnpm storybook, which opens Storybook in the browser.

An up-to-date version of all Storybook components can be found online.

Backend: Overall Structure

• Resolver aggregates the data, and transforms in a representation suitable for the domain layer.
• Service performs input validation, authorization, sorting, and implements the business logic.
• Data layer is handled by Prisma.

Directories

• api contains the backend.
• assets contains uncompiled assets such as styles, images, or fonts. The content of this folder will be processed by webpack, e.g. CSS has pre-processor applied.
• components is where we put all our Vue.js components which are then imported into the pages.
• layouts contains the layouts that determine the look and feel. Nuxt documentation.
• middleware defines custom functions that are run before rendering either a page or a group of pages. Nuxt documentation.
• pages contains the application's views and routes. Nuxt reads all the *.vue files inside this directory and creates the router of your application.
• plugins contains Javascript plugins that are run before mounting the root Vue.js application. Nuxt documentation.
• static is directly mapped to the server root and contains files that have to keep their names (e.g. robots.txt) or likely won't change (e.g. the favicon). Files in this folder are not processed by webpack.
• store contains Vuex Store files. Nuxt documentation.

Recommended VS Code and Browser extensions

• Volar: Add syntax highlighting and other tooling for Vue. It is also recommended to activate the takeover mode.
• Prisma: Add syntax highlighting, formatting, jump-to-definition and linting for Prisma Schema files.
• Prettier: Format code and enforces consistent style.
• EditorConfig: Override user/workspace VS Code settings with the provided settings in .editorconfig.
• Tailwind CSS: IntelliSense enhancement to support Tailwind.
• Vitest: Add integration of Vitest, i.e., visual overview of the tests and easy debugging of tests.
• GraphQL: Add syntax highlighting and IntelliSense for GraphQL.
• Debugger for Firefox or Chrome: Allow debugging web applications from within VS Code.
• Vue.js devtools: Browser integration for debugging and investigation for Firefox
• Apollo Client Devtools: Debug and analyze GraphQL on the client side for Firefox

Technologies used

• Vue.js: UI framework Documentation
• NuxtJS: Vue framework Documentation
• Prisma: Documentation
• Graphql:
  • GraphQL code generator: Documentation
  • Vue Apollo: Graphql integration for Vue Documentation
• Tailwind CSS: CSS framework Documentation, including Vue Tailwind to extract reusable components
• Iconify: Font-based icons
• Storybook: Visual testing

Conventions

• Vue: Single File Components are used for all components, with a PascalCase name.
• Tests are placed next to the file containing the code-under-test, and have the same file name with a .spec.ts suffix added. For example,

  api
  │   Resolver.ts
  │   Resolver.spec.ts
  

• Commit messages and pull request titles follow the structure of Conventional Commits. The following prefixes are used:
  • feat: Introduces a new feature or provides an enhancement of an existing feature
  • fix: Patches a bug
  • refactor: A code change that neither fixes a bug nor adds a feature
  • test: Adds missing tests or corrects existing tests
  • docs: Documentation only changes
  • chore: Changes to the build process or auxiliary tools and libraries such as CI or package updates

References

• Prisma used in different contexts: https://github.com/prisma/prisma-examples
• Example application using Prisma and Apollo: https://github.com/poulainv/tottem
• Example application using Nuxt: https://github.com/gyarasu/nuxt-full-stack-template
• Example application for authentication using GraphQL Shield and Prisma: https://github.com/prisma/prisma-examples/tree/latest/typescript/graphql-auth
• Example server using Prisma and GraphQL: https://github.com/prisma-labs/graphql-prisma-typescript
• Example application for vue-apollo: https://github.com/Akryum/vue-apollo-todos
• Example application using a similar stack as we (GraphQL, Vue): https://github.com/Akryum/guijs/tree/master/packages/@guijs
• Best practices: Node

Sponsors

Thanks to Chromatic for providing the visual testing platform that helps us review UI changes and catch visual regressions.