ccloud-ui

This is the front end for the Culture Clould application using React, Node.js, Express and Webpack. It is also configured with webpack-dev-server, eslint, prettier and babel.

Prerequisites

Configure your .npmrc file and GitHub account.

Clone the repository

git clone https://github.com/octanner/ccloud-ui

cd ccloud-ui

Create and configure the .env file

Create the .env from example file:

cp .env.example .env

Then, copy the environment variables that you are missing from the QA config into the .env file. Make sure to also remove all end of line comments:

aka config -a ccloudui-core-qa

or

https://akkeris.octanner.io/apps/ccloudui-core-qa/config

Build and run the web app locally

# Install required node_modules
yarn

# Start both front end and back end servers (accessible @ http://localhost:3000)
yarn dev

Build and run the web app for production

# Build for production
yarn build

# Start production server
yarn start

VS Code Debugging

Start the dev server in any terminal. Navigate to the VS Code debugger in the Activity Bar. Select "Attach by Process ID" in the dropdown. Hit play. Select Node src/server/index.js. Set debugging points. Execute code that will hit the desired debugging points. In the bottom panel, navigate to the debug console. You should now be able to execute commands.

Documentation

ESLint

Using Airbnb's Javascript Style Guide with some exceptions. Turned off no-console, comma-dangle and react/jsx-filename-extension rules.

OpenAPI docs

The OpenAPI documentation can be accessed at

https://octanner.github.io/ccloud-ui/

To update the OpenAPI docs, update docs/openapi.yaml file.

Preview Apps

A preview site will automatically be created for each pull request. Be sure to use the prieview site URL (i.e. https://cc-qaXXXXX.octanner.app), not the preview app URL (i.e. https://cclouduiXXXXX-core-qa.alamoapp.octanner.io).

Mocking our Graphql Schema

Why?

The ultimate goal of using GraphQL as part of our stack is to create a productive separation between FE and BE during development. Now you can start and finish client-side features before our servers support them by mocking our servers.

1. You can build complex queries and test them without messing with our servers.
2. You can implement new resolvers that mimic how the BE will handle a request.
3. You have at your disposal ALL the types you would need to build new resolvers

How(to use mocking as part of your front end development)?

coming soon. I will write up a suggested workflow.

Main Scripts To Mock CC GraphQL Server

# Generates a copy of the API schema we use to make queries and mutations in this repository
# Auto generates mockServer/schema.graphql
yarn mock:introspect

# Generation of typed queries, mutations, subscriptions and typed GraphQL resolvers based on https://graphqlgateway-core-qa.alamoapp.octanner.io/graphql.
# https://www.the-guild.dev/graphql/codegen
# Auto generates mockServer/__generated__/resolver-types.ts
yarn generate:types

# Concurrently, run dev and start the mock server at localhost:4000
# This also has a REACT_APP_MOCK flag that soon will tell our Next app to look at localhost:4000 instead of graphqlgateway-core-qa
yarn mock:dev

Remaining Mocking Commands

# Soon, the only way to fetch our schema
yarn mock:schema

# Generation of typed queries, mutations, subscriptions and typed GraphQL resolvers based on mockServer/schema.graphql.
# unlike "mock:introspect", this script requires authenticating Rover with Apollo Studio.
yarn generate:local:types

# Starts mock server on port 4000. Without starting dev.
yarn mock:server

Dev Details

In order to be able to log into each new preview site, a new Core Auth web client needs to be created for each one. To accomplish this a webhook has been setup on ccloudui-core-qa (the source app) that will fire on the creation of each new preview app. This POST request will hit an endpoint on the Core Auth API that will 1) create the new Core Auth web client, and 2) inject the necessary config vars into the app.

Webhook details:

$ aka hooks -a ccloudui-core-qa
ɧ https://ssoinject-core-stg.alamoapp.octanner.io/coreauth/client/create-from-akkeris-webhook?post_login_route=/api/ssoredirect&post_logout_route=/
  Events: preview
  Id: f181dd67-a5dc-49fb-a8b7-536171d75418
  Active: true

To break this down:

1. The Core Auth API is ssoinject-core-stg. Note that we should always be using Core's stage environment for any non-prod apps.
2. The endpoint on that API is /coreauth/client/create-from-akkeris-webhook.
3. The available query params are post_login_route and post_logout_route.

See the Core Auth documentation for further details.