Getting started

It is very simple to get started with Paperbits. Just follow the steps below and you’ll get up and running in minutes.

Step 1. Launch demo project locally

To run demo website locally, you'll need:

1.1. Clone the demo project from GitHub:

> git clone https://github.com/paperbits/paperbits-demo.git

1.2. Switch into just cloned directory:

> cd paperbits-demo

1.3. Install packages required for work:

> npm install

1.4. Run demo site:

> npm start

This will build the project and launch demo website where you can start modifying its content.

Step 2. Make changes to demo content

Content editors that you see on demo website are pretty powerful and allow you to do many things: add/delete pages and blog posts, modify their content, switch and configure viewports, change site favicon, drop external files or google map links, and more (please refer to Feature index to see full list). Therefore, feel free to explore and go as wild as you wish.

Since this is demo project that only showcases editing experience, all the modifications you make are saved in browser’s local storage (if you’d like to try with a real storage, i.e. Firebase, GitHub or your own backend, please follow the respective tutorials).

When you are done changing the content, you can download the data from local storage by pressing Ctrl+S (or ⌘+S) and use it in the next step to publish your static website.

Step 3. Publish modified content

Demo project comes with “publish” task.

> npm run publish

If you run this command, it will generate a static website in ./dist/website/ folder of the project. The data used for publishing is taken from file demo.json, which you can find in /src/data/ folder.

Therefore, if you replace this file with the one you downloaded on Step 2, you’ll get your changes published.

Step 4. Switch to Firebase

Now, when you’re ready to switch to real storage, let’s take a look at the components involved in data management, how they are plugged in and how you can replace them.

First of all, here’s a couple of most important interfaces:

IObjectStorage - key/value object storage that is suitable for managing flat and tree-like structures.

IBlobStorage - key/value blob storage for uploading/downloading files.

Depending on project those interfaces may have different implementations. For instance, our demo website works with StaticObjectStorage and StaticBlobStorage respectively. These two storages, as mentioned above, keep all your changes in browser’s local storage and are used primarily for demo purposes and in this step we’re going to swap them with FirebaseObjectStorage and FirebaseBlobStorage to make it closer to real-life setup.

Now, let’s do the actual replacement.

4.1. Install Firebase module

> npm install @paperbits/firebase --save

4.2. Remove Demo module and plug-in Firebase module

You can do it in /src/startup.design.ts file:

...
/* Uncomment to enable Firebase module */
import { FirebaseModule } from "@paperbits/firebase/firebase.module";
...
/* Uncomment to enable Firebase module */
injector.bindModule(new FirebaseModule());
...

4.3. Create Firebase Realtime Database

Go to Firebase console and click “Add new project”, then follow the steps of the dialog. After the project is created, click “Database” section and choose “Realtime Database”.

4.4. Upload demo.json

Click three vertical dots (in the top right corner) of the window and, in the drop-down menu, click "Import JSON" option which opens up “Import” dialog where you'll need to specify /data/demo.json file.

4.5. Configure Firebase authentication

Go back to “Authentication” section and click “Sign-In Method” tab, where you need to enable “Basic” authentication provider.

Note: Here we use “Basic” provider for tutorial purposes, later on you’ll learn how to use any other authentications, i.e. Google or GitHub.

Now switch to “Users” tab and add a new user with username and password you like (you’ll need them in the next step).

4.6. Place connection strings to config.design.json

Go to “Authentication”, then click WEB SETUP (a link in the top right corner) to view the configuration and copy it into the file /src/config.design.json:

Don’t forget to specify username and password acquired in the previous step.

{
    "firebase": {
        "apiKey": "< your API key >",
        "authDomain": "< your domain >.firebaseapp.com",
        "databaseURL": "https://< your database URL >.firebaseio.com",
        "projectId": "< your project ID >",
        "storageBucket": "< your storage bucket >.appspot.com",
        "databaseRootKey": "/",
        "storageBasePath": "/",
        "auth": {
            "basic": {
                "email": "< email >",
                "password": "< password >"
            }
        }
    }
}

4.7. Run demo site again

> npm start

This time the data flows from Firebase and when you save (Ctrl+S or ⌘+S) your changes they do get preserved in the new data store.

Step 5. Host website in Firebase

Finally, you may want to deploy your website to Firebase Hosting. Please refer to Firebase Hosting documentation.