This repository contains the source of the JabRef homepage.
- 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
alice@jabref.org / EBNPXY35TYkYXHs
. - PR previews: Every pull request is deployed to a (temporary) server, which uses the same test data as the "Test server".
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 port6380
or, alternatively, add the configurationREDIS_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 usepnpm 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.
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. |
- Prototype your new feature by making the necessary changes to
schema.prisma
. - Run
pnpm prisma:push
to push the changes to the local database. - Iterate until feature is ready.
- Run
pnpm prisma:migrate:dev
to generate new migration based on the schema changes.
See Prisma documentation for more details.
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.
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.
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.
- 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
- 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
- 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 featurefix
: Patches a bugrefactor
: A code change that neither fixes a bug nor adds a featuretest
: Adds missing tests or corrects existing testsdocs
: Documentation only changeschore
: Changes to the build process or auxiliary tools and libraries such as CI or package updates
- 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
Thanks to Chromatic for providing the visual testing platform that helps us review UI changes and catch visual regressions.