Setting up a new project

A walk through for creating and setting up a new project using the Primo skeleton as a foundation.

What the skeleton is and what it isn't

This skeleton is intended to be an opinionated starting point for new, straight-forward content-managed websites. It is an effort to minimise duplication of effort as opposed to duplication of code. The project is meant to be cloned and then pushed to a new origin rather than forked. So, if you don't like the default choices made, by all means fork it and change them and use that as a starting point for your apps and websites.

Notable choices made

Basic installation

After cloning and installing the PHP dependencies, the app should be ready to run using PHP’s built-in cli server and the content of this documentation website.

The following assumes that you a) have composer installed and that b) you have the composer binary on your $PATH.

$ git clone [email protected]:netglue/primo-skeleton.git my-app
...
$ cd my-app
$ composer install
...
$ php -S 0.0.0.0:8080 -t public/

Opening http://localhost:8080 in your browser post installation should yield this website.

Kill off the existing git origin and push to your newly created repository:

$ git remote set-url origin https://github.com/USERNAME/REPOSITORY.git
$ git push -u origin master

Changing the content repository

This is all very well, but you are likely not re-skinning the content of this website, so you'll need to configure your content repository.

Sign up, or sign in to Prismic and create a new, blank repository or pick an existing repo. Armed with your repository url and an access token (if you have configured your repository to require one), enter this information into a configuration file:

<?php
// config/autoload/prismic.local.php

return [
  'prismic' => [
    'api' => 'https://my-repo.cdn.prismic.io/api/v2',
    'token' => null, // Your access token if required
  ],
];

Your content model

Your new repository will not have any custom document types yet. The skeleton ships with the document type definitions used for this website. You can find them in ./frontend/types/dist/*.json - These JSON files are built from PHP source files because it gets tedious and repetitive to craft document types by hand in JSON. The PHP sources can be found in the sibling src directory ./frontend/types/src/*.php.

The PHP sources are quite terse because they use a builder tool that comes with netglue/prismic-cli. You can compile these using the command $ vendor/bin/laminas primo:build manually and upon each change you make to the source files, or, you can install the javascript dependencies and make use of npm-watch to do it for you.

If you have node and npm installed already, you can issue an npm install at the root of the project to install all of the dependencies. Once this has completed, you can issue npm run watch and all changes to the styles, javascript and document types will be recompiled on demand.

Assuming you've read the documentation on building custom types and you are familiar with the Prismic dashboard, you can copy and paste the content of your JSON files into the custom type editor on the Prismic dashboard.

One day, they'll release an API to push custom document types 🤞

Templating

Please take a good look around the ./src/App/templates directory in the project to get a feel for presenting your content in templates. The most important thing to remember is that you cannot guarantee that any of your content fields are actually there because Prismic does not enforce constraints on whether certain bits of content are required or not. It's an important concept that works really well for writers but it does mean a lot more checks in your code. It's a bone of contention, but personal opinion is that Prismic have the right approach and that it leads to more stability.