dspace-angular

The DSpace User Interface built on Angular, written in TypeScript and using Angular Universal.

DSpace open source software is a turnkey repository application used by more than 2,000 organizations and institutions worldwide to provide durable access to digital resources. For more information, visit https://dspace.org/

DSpace consists of both a Java-based backend and an Angular-based frontend.

• Backend (https://github.com/DSpace/DSpace/) provides a REST API, along with other machine-based interfaces (e.g. OAI-PMH, SWORD, etc)
  • The REST Contract is at https://github.com/DSpace/RestContract
• Frontend (this codebase) is the User Interface built on the REST API

• Backend (REST API): https://github.com/DSpace/DSpace/releases
• Frontend (User Interface): https://github.com/DSpace/dspace-angular/releases

On our wiki, you may also find a list of all past releases, including their current levels of support.

Documentation for each release may be viewed online or downloaded via our Documentation Wiki.

The latest DSpace Installation instructions are available at: https://wiki.lyrasis.org/display/DSDOC10x/Installing+DSpace

Ensure you're running Node v20.x, v22.x or v24.x, npm >= v10.x

# clone the repo
git clone https://github.com/DSpace/dspace-angular.git

# change directory to our repo
cd dspace-angular

# install the local dependencies
npm install

# start the server
npm start

Then go to http://localhost:4000 in your browser

Not sure where to start? watch the training videos linked in the Introduction to the technology section below.

• Introduction to the technology
• Requirements
• Installing
  • Configuring
• Running the app
  • Running in production mode
  • Deploy
  • Running the application with Docker
• Cleaning
• Testing
  • Test a Pull Request
  • Unit Tests
  • E2E Tests
    • Writing E2E Tests
• Documentation
• Other commands
• Recommended Editors/IDEs
• Collaborating
• File Structure
• Managing Dependencies (via npm)
• Frequently asked questions
• License

You can find more information on the technologies used in this project (Angular.io, Angular CLI, Typescript, Angular Universal, RxJS, etc) on the LYRASIS wiki

• Node.js
• Ensure you're running node v20.x, v22.x or v24.x

If you have nvm or nvm-windows installed, which is highly recommended, you can run nvm install --lts && nvm use to install and start using the latest Node LTS.

• npm install to install the local dependencies

Default runtime configuration file is located in config/ folder. These configurations can be changed without rebuilding the distribution.

To override the default configuration values, create local files that override the parameters you need to change. You can use config.example.yml as a starting point.

• Create a new config.(dev or development).yml file in config/ for a development environment;
• Create a new config.(prod or production).yml file in config/ for a production environment;

The settings can also be overwritten using an environment file or environment variables.

This file should be called .env and be placed in the project root.

The following non-convention settings:

DSPACE_HOST # The host name of the angular application
DSPACE_PORT # The port number of the angular application
DSPACE_NAMESPACE # The namespace of the angular application
DSPACE_SSL # Whether the angular application uses SSL [true/false]

All other settings can be set using the following convention for naming the environment variables:

1. replace all . with _
2. convert all characters to upper case
3. prefix with DSPACE_

e.g.

# The host name of the REST application
rest.host => DSPACE_REST_HOST

# The port number of the REST application
rest.port => DSPACE_REST_PORT

# The namespace of the REST application
rest.nameSpace => DSPACE_REST_NAMESPACE

# Whether the angular REST uses SSL [true/false]
rest.ssl => DSPACE_REST_SSL

cache.msToLive.default => DSPACE_CACHE_MSTOLIVE_DEFAULT
auth.ui.timeUntilIdle => DSPACE_AUTH_UI_TIMEUNTILIDLE

The equavelant to the non-conventional legacy settings:

DSPACE_UI_HOST => DSPACE_HOST
DSPACE_UI_PORT => DSPACE_PORT
DSPACE_UI_NAMESPACE => DSPACE_NAMESPACE
DSPACE_UI_SSL => DSPACE_SSL

The same settings can also be overwritten by setting system environment variables instead, E.g.:

export DSPACE_HOST=demo.dspace.org
export DSPACE_UI_PORT=4000

The priority works as follows: environment variable overrides variable in .env file overrides external config set by DSPACE_APP_CONFIG_PATH overrides config.(prod or dev).yml

These configuration sources are collected at run time, and written to dist/browser/assets/config.json for production and src/app/assets/config.json for development.

The configuration file can be externalized by using environment variable DSPACE_APP_CONFIG_PATH.

Buildtime configuration must defined before build in order to include in transpiled JavaScript. This is primarily for the server. These settings can be found under src/environment/ folder.

To override the default configuration values for development, create local file that override the build time parameters you need to change.

• Create a new environment.(dev or development).ts file in src/environment/ for a development environment;

If needing to update default configurations values for production, update local file that override the build time parameters you need to change.

• Update environment.production.ts file in src/environment/ for a production environment;

The environment object is provided for use as import in code and is extended with the runtime configuration on bootstrap of the application.

Take caution moving runtime configs into the buildtime configuration. They will be overwritten by what is defined in the runtime config on bootstrap.

To use environment variables in a UI component, use:

import { AppConfig, APP_CONFIG } from 'src/config/app-config.interface';
...
constructor(@Inject(APP_CONFIG) private appConfig: AppConfig) {}
...

or

import { environment } from '../environment.ts';

After you have installed all dependencies you can now run the app. Run npm run start:dev to start a local server which will watch for changes, rebuild the code, and reload the server for you. You can visit it at http://localhost:4000.

When building for production we're using Ahead of Time (AoT) compilation. With AoT, the browser downloads a pre-compiled version of the application, so it can render the application immediately, without waiting to compile the app first. The compiler is roughly half the size of Angular itself, so omitting it dramatically reduces the application payload.

To build the app for production and start the server (in one command) run:

npm start

This will run the application in an instance of the Express server, which is included.

If you only want to build for production, without starting, run:

npm run build:prod

This will build the application and put the result in the dist folder. You can copy this folder to wherever you need it for your application server. If you will be using the built-in Express server, you'll also need a copy of the node_modules folder tucked inside your copy of dist.

After building the app for production, it can be started by running:

npm run serve:ssr

NOTE: At this time, we do not have production-ready Docker images for DSpace. That said, we do have quick-start Docker Compose scripts for development or testing purposes.

See Docker Runtime Options

# clean everything, including node_modules. You'll need to run npm install again afterwards.
npm run clean

# clean files generated by the production build (.ngfactory files, css files, etc)
npm run clean:prod

# cleans the distribution directory
npm run clean:dist

If you would like to contribute by testing a Pull Request (PR), here's how to do so. Keep in mind, you do not need to have a DSpace backend / REST API installed locally to test a PR. By default, the dspace-angular project points at our demo REST API

1. Pull down the branch that the Pull Request was built from. Easy instructions for doing so can be found on the Pull Request itself.
   • Next to the "Merge" button, you'll see a link that says "command line instructions".
   • Click it, and follow "Step 1" of those instructions to checkout the pull down the PR branch.
2. npm run clean (This resets your local dependencies to ensure you are up-to-date with this PR)
3. npm install (Updates your local dependencies to those in the PR)
4. npm start (Rebuilds the project, and deploys to localhost:4000, by default)
5. At this point, the code from the PR will be deployed to http://localhost:4000. Test it out, and ensure that it does what is described in the PR (or fixes the bug described in the ticket linked to the PR).

Once you have tested the Pull Request, please add a comment and/or approval to the PR to let us know whether you found it to be successful (or not). Thanks!

Unit tests use the Jasmine test framework, and are run via Karma.

You can find the Karma configuration file at the same level of this README file:./karma.conf.js If you are going to use a remote test environment you need to edit the ./karma.conf.js. Follow the instructions you will find inside it. To executing tests whenever any file changes you can modify the 'autoWatch' option to 'true' and 'singleRun' option to 'false'. A coverage report is also available at: http://localhost:9876/ after you run: npm run coverage.

The default browser is Google Chrome.

Place your tests in the same location of the application source code files that they test, e.g. ending with *.component.spec.ts

and run: npm test

If you run into odd test errors, see the Angular guide to debugging tests: https://angular.io/guide/test-debugging

E2E tests (aka integration tests) use Cypress.io. Configuration for cypress can be found in the cypress.json file in the root directory.

The test files can be found in the ./cypress/e2e/ folder.

Before you can run e2e tests, two things are REQUIRED:

1. You MUST be running the DSpace backend (i.e. REST API) locally. The e2e tests will NOT succeed if run against our demo/sandbox REST API (https://demo.dspace.org/server/ or https://sandbox.dspace.org/server/), as those sites may have content added/removed at any time.
   • After starting up your backend on localhost, make sure either your config.prod.yml or config.dev.yml has its rest settings defined to use that localhost backend.
   • If you'd prefer, you may instead use environment variables as described at Configuring. For example:

     DSPACE_REST_SSL = false
     DSPACE_REST_HOST = localhost
     DSPACE_REST_PORT = 8080
     

2. Your backend MUST include our Entities Test Data set. Some tests run against a specific Community/Collection/Item UUID. These UUIDs are all valid for our Entities Test Data set.
   • (Recommended) The Entities Test Data set may be installed easily via Docker, see https://github.com/DSpace/DSpace/tree/main/dspace/src/main/docker-compose#ingest-option-2-ingest-entities-test-data
   • Alternatively, the Entities Test Data set may be installed via a simple SQL import (e. g. psql -U dspace < dspace7-entities-data.sql). See instructions in link above.

After performing the above setup, you can run the e2e tests using

ng e2e

NOTE: By default these tests will run against the REST API backend configured via environment variables or in config.prod.yml. If you'd rather it use config.dev.yml, just set the NODE_ENV environment variable like this:

NODE_ENV=development ng e2e

The ng e2e command will start Cypress and allow you to select the browser you wish to use, as well as whether you wish to run all tests or an individual test file. Once you click run on test(s), this opens the Cypress Test Runner to run your test(s) and show you the results.

All E2E tests must be created under the ./cypress/e2e/ folder, and must end in .spec.ts. Subfolders are allowed.

• The easiest way to start creating new tests is by running ng e2e. This builds the app and brings up Cypress.
• From here, if you are editing an existing test file, you can either open it in your IDE or run it first to see what it already does.
• To create a new test file, click