SANDstack Starter
This project is a starter for building a SANDstack (Sveltejs/Sapper, Apollo GraphQL, Neo4j Database) application. There are two components to the starter, the UI application (a Svelte/Sapper app) and the API app (GraphQL server).
This project used as a starting point the api component from the GRANDstack project and the default Sapper template.
The master branch DOES NOT USE Svelte Apollo There is a separate branch that demonstrates it's use.
If you are new to Svelete this is a good introductory video
The GRANDStack documentation provides a good overview of the Neo4j GraphQL integration.
Setting up a development environment
Follow these instructions first
Quickstart
You can quickly start using Docker engine version 19 or later:
docker-compose -f docker-compose.yml -f docker-compose-stage.yml up --build
List the running containers:
docker ps
There should be three containers started:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
625acfa444fa sand-stack-starter_ui "docker-entrypoint.s…" 3 minutes ago Up 2 minutes 0.0.0.0:3000->3000/tcp sand-stack-starter_ui_1
843c5ea8d997 sand-stack-starter_api "docker-entrypoint.s…" 3 minutes ago Up 2 minutes 0.0.0.0:4001->4001/tcp sand-stack-starter_api_1
8ae79170f66e sand-stack-starter_neo4j "/sbin/tini -g -- /d…" 3 minutes ago Up 3 minutes 0.0.0.0:7474->7474/tcp, 7473/tcp, 0.0.0.0:7687->7687/tcp sand-stack-starter_neo4j_1
Initially the database is empty. Running the test suite automatically loads the database with sample data.
Open a new terminal
cd test
npm install
npx cypress run
The application should be running at localhost:3000
Development mode
The project is set up to allow the api and ui servers to run in dev mode. This mode enables a watch on all files and automatically deploys when changes are saved. The following instructions show you how to start each server component separately.
If you've run the docker-compose script be sure to shut down the docker containers before starting in development mode.
docker-compose down
Be sure your development machine is running Node version 12.
node --version
Neo4j
There are many ways to run Neo4j for development purposes. The README in the neo4j directory describes several approaches. However the simplest is to start a stand alone Docker container using the DockerFile provided.
docker-compose up --detach --remove-orphans
List the running containers:
docker ps
You should see a neo4j container:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
3c95a2947d49 neo4j "/sbin/tini -g -- /d…" 9 seconds ago Up 8 seconds 0.0.0.0:7474->7474/tcp, 7473/tcp, 0.0.0.0:7687->7687/tcp neo4j-db
You should now be able to access the Neo4j database browser at localhost:7474 (you can log in using neo4j/letmein). Click the *() under Node Labels to list a sample of nodes.
Install dependencies
(cd ../ui && npm install)
(cd ../api && npm install)
Start API Server
Open a new terminal
cd api
npm run dev
This will start the GraphQL API server in dev mode.
You should also be able to access the Apollo GraphQL playground at localhost:4001/graphql This allows you to interactively test your GraphQL before using it in your application.
Start UI Server
Open a new terminal
cd ui
npm run dev
This will start the Svelte Sapper app in dev mode. In dev mode when a file change is saved in the ui directory the web page should automatically reload with the changes.
Start Cypress Test Server
Open a new terminal
cd test
npx cypress open
The test runner lets you select the browser you wish to use for testing.
We've found as as apps get larger and more complex it is often necessay to add cy.wait(time) to make the test stable on slower CI machines. These are end to end tests so many factors can affect test performance.
Github Continuous Integration
The /.github/workflows/test.yml is a Github action that runs the Cypress end to end tests and stores the test results to github on every push.
Sapper Export
This simple example is a readonly app and a candidate for Sapper Export
For the export to run properly the neo4j and api servers must be running.
Open a new terminal
cd ui
npx sapper export
This will create a /ui/__sapper__/export folder with a production-ready build of your site. You can launch it like so:
npx serve __sapper__/export
Sapper Environment
The ui app makes use of the Sapper Environment npm. These are environment variables that are replaced at build time by rollup.config.js so they can be used in client code. Any environment variable with prefix SAPPER_APP_ is for use in the client code.
We make especial use of this in /ui/src/apollo.js. The Apollo GraphQl client is used in both the browser and SSR. In dev mode they have the same value.
SSR_GRAPHQL_URI=http://localhost:4001/graphql
SAPPER_APP_GRAPHQL_URI=http://localhost:4001/graphql
However in production they are often different as the SAPPER_APP_GRAPHQL_URI is the public address of the api server and SSR_GRAPHQL_URI is the internal address of the server. An example of this can be seen in docker-compose-stage.yml.
