Installation Guide

You can use the Viewer with our CDN or with our npm package. Both variants have their advantages, so it's on you to choose.

If you don't know what is right for you, you'll probably be better off with the CDN. The npm version is for larger projects that might always use npm.

We also have an advanced react example that you can use as a starting foundation. Go check it out!

Current Version

Installation with NPM

You can install the Viewer with npm. To install the module, open a terminal window in you project and run:

BASH

npm install --save @shapediver/viewer

The package will be downloaded and installed for you. You can also have a look at this CodeSandBox for an example setup.

Detailed installation with NPM and Webpack

If you are having issues with the setup or are just not that familiar with setting up projects, you can find a detailed guide on how to setup a project from the start here.

Detailed NPM Installation Guide

Package Installation

First of all, you need to have a version of npm installed. We currently use version 7.7.6, but any newer version should be fine.

Then, let's call some npm tasks and install some dependencies. Go to an empty folder that you want to use and call these commands. Some might not be necessary for you if you are integrating the viewer into an existing setup. This command just initializes npm for this project and creates the package.json file that is needed.

BASH

npm init --yes

Then we install some development dependencies. The first one is typescript, as we are using TypeScript in this example, we also have to install the dependency for it. The next three are all dependencies for webpack, we get to that later on.

BASH

npm install --save-dev typescript webpack webpack-cli ts-loader

Then, we install the actual Viewer dependency.

BASH

npm install --save @shapediver/viewer

Adjusting Config Files

First, we create a file called tsconfig.json in the root of the project and add this content to it.

JSON

{
  "compilerOptions": {
    "outDir": "./dist/",
    "module": "es6",
    "target": "es2015",
    "moduleResolution": "node"
  }
}

Then, we create a webpack.config.js file in the root of the directory and again, add some content to it. Here the package ts-loader is used, as webpack normally doesn't work with TypeScript files.

JS

const path = require('path');
module.exports = {
  entry: './src/index.ts',
  mode: 'production',
  module: {
    rules: [{
      test: /\.tsx?$/,
      use: 'ts-loader',
      exclude: /node_modules/,
    }],
  },
  resolve: {
    extensions: ['.tsx', '.ts', '.js']
  },
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist')
  }
};

Building

To build the project, in our package.json we just need to add a small script for that. Currently there is only a test script in there, we now add a build script to make it look like this:

JSON

"scripts": {
  "build": "webpack"
}

On the main viewer page, we create a simple example, that can be built now with the command npm run build. To try this out, just create a simple http-server in this folder and load the index.html.

Installation with CDN

In you html-head section, simply add our bundle.

HTML

<script src="https://viewer.shapediver.com/v3/VERSION_NUMBER/bundle.js"></script>

Note: Please select a fixed version by replacing VERSION_NUMBER with a version number (example X.X.X). If you want to update to a newer viewer version at some point, please go through our migration guide.

You can also have a look at this CodeSandBox for the complete setup.

Additional CodeSandBoxes

HTMLDivElement structure
A proper structure so that the viewer elements are displayed correctly.
Closing
Closing of viewports and sessions.

Multiple Viewports or Sessions

Multiple Sessions
Creating multiple sessions in a single viewport.
Multiple Sessions - Visibility
Creating multiple sessions in a single viewport and creating toggles for their visibility.
Multiple Sessions - Multiple Viewports
Creating multiple sessions in multiple viewports.
Multiple Viewports - Hiding Geometry
Creating multiple viewports and hiding parts of the geometry.
Multiple Viewports - Hiding Geometry 2
Creating multiple viewports and hiding parts of the geometry.
Multiple Viewports - Environment Geometry Updates
Creating multiple viewports and hiding parts of the geometry. Then, updating the environment geometry to fit to the updated geometry.