Merge pull request #142 from lsst-sqre/tickets/DM-40259

DM-40259: Update storybook to v7 and adopt pnpm

.github/workflows/chromatic.yaml

@@ -16,11 +16,15 @@ jobs:
         with:
           fetch-depth: 0 # get full Git history
 
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 8
+
       - name: Set up node
         uses: actions/setup-node@v3
         with:
           node-version-file: '.nvmrc'
-          cache: 'npm'
+          cache: 'pnpm'
 
       - name: Authenticate GitHub Packages
         run: |
@@ -29,7 +33,7 @@ jobs:
           NPM_PKG_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Install npm packages
-        run: npm ci
+        run: pnpm install
 
       - name: Publish to Chromatic
         if: github.ref != 'refs/heads/main'

.github/workflows/ci.yaml

@@ -41,6 +41,10 @@ jobs:
         id: node_version
         run: echo ::set-output name=NODE_VERSION::$(cat .nvmrc)
 
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 8
+
       - name: Authenticate GitHub Packages
         run: |
           echo "//npm.pkg.github.com/:_authToken=${NPM_PKG_TOKEN}" > ~/.npmrc
@@ -51,18 +55,18 @@ jobs:
         uses: actions/setup-node@v3
         with:
           node-version: ${{ steps.node_version.outputs.NODE_VERSION }}
-          cache: 'npm'
+          cache: 'pnpm'
 
       - name: Install npm packages
-        run: npm ci
+        run: pnpm install
 
       - name: Lint
         run: |
-          npm run lint
-          npm run format:check
+          pnpm run lint
+          pnpm run format:check
 
       - name: Build site
-        run: npm run build
+        run: pnpm run build
 
   docker:
     needs:
@@ -109,7 +113,6 @@ jobs:
           # Only push tags or ticket branches
           push: true
           tags: |
-            lsstsqre/squareone:${{ steps.vars.outputs.tag }}
             ghcr.io/lsst-sqre/squareone:${{ steps.vars.outputs.tag }}
           target: production
           cache-from: type=gha

.storybook/main.js → .storybook/main.ts

@@ -1,22 +1,21 @@
-const path = require('path');
+import type { StorybookConfig } from '@storybook/nextjs';
 
-module.exports = {
+const config: StorybookConfig = {
   stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
   addons: [
     '@storybook/addon-links',
     '@storybook/addon-essentials',
     '@storybook/addon-interactions',
     '@storybook/addon-a11y',
-    {
-      name: 'storybook-addon-next',
-      options: {
-        nextConfigPath: path.resolve(__dirname, '../next.config.js'),
-      },
-    },
   ],
-  framework: '@storybook/react',
+  framework: '@storybook/nextjs',
   core: {
     builder: '@storybook/builder-webpack5',
   },
   staticDirs: ['../public'],
+  docs: {
+    autodocs: true,
+  },
 };
+
+export default config;

.vscode/tasks.json

@@ -12,6 +12,13 @@
         "isDefault": true
       }
     },
+    {
+      "type": "npm",
+      "script": "lint",
+      "problemMatcher": [],
+      "label": "npm: lint",
+      "detail": "next lint"
+    },
     {
       "type": "npm",
       "script": "storybook",

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Change log
 
+## Unreleased
+
+### Other changes
+
+- Migrated to `pnpm` from `npm` for package management.
+- Upgrade to Storybook 7.
+- Add development set up documentation to the squareone.lsst.io site.
+
 ## 0.10.0 (2023-03-27)
 
 ### New features

Dockerfile

@@ -12,16 +12,18 @@ WORKDIR /app
 
 RUN echo "//npm.pkg.github.com/:_authToken=${GH_PKG_TOKEN}" > ~/.npmrc
 
-COPY package.json package-lock.json .npmrc ./
-RUN npm ci
+COPY package.json pnpm-lock.yaml .npmrc ./
+RUN npm install -g pnpm
+RUN pnpm install
 
 # Stage 2: Build application ==================================================
-from node:16-alpine as builder
+FROM node:16-alpine as builder
 
 WORKDIR /app
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .
-RUN npm run build
+RUN npm install -g pnpm
+RUN pnpm run build
 
 # Stage 3: Install pre-built app and deps for production ======================
 FROM node:16-alpine as production

README.md

@@ -0,0 +1,17 @@
+# Squareone
+
+[![GitHub Actions](https://github.com/lsst-sqre/squareone/actions/workflows/ci.yaml/badge.svg)](https://github.com/lsst-sqre/squareone/actions/) [![Documentation](https://img.shields.io/badge/squareone-lsst.io-brightgreen.svg)](https://squareone.lsst.io)
+
+Squareone is the home page for the [Rubin Science Platform](https://data.lsst.cloud). It's where you start on your journey to use the RSP's portal, notebooks, and APIs to do science with Rubin/LSST data. [Squareone is deployed with Phalanx](https://phalanx.lsst.io/applications/squareone/).
+
+**Documentation for developers and operators:** https://squareone.lsst.io
+
+## Technology stack
+
+- The site is built with [Next.js](https://nextjs.org) and [React](https://reactjs.org). Next.js allows the site to be dynamically configured for different Science Platform deployments.
+
+- Styling is done through [styled-components](https://styled-components.com) (along with global CSS).
+
+## Development
+
+To set up your development environment and run the site locally, see Squareone's development documentation: https://squareone.lsst.io/dev/

docs/_rst_epilog.rst

@@ -1,2 +1,15 @@
+
 .. _CommonMark: https://commonmark.org/
 .. _MDX: https://mdxjs.com
+.. _Next.js: https://nextjs.org
+.. _next lint: https://nextjs.org/docs/basic-features/eslint
+.. _nvm: https://nvm.sh
+.. _Phalanx: https://phalanx.lsst.io
+.. _pnpm: https://pnpm.io
+.. _Prettier: https://prettier.io/
+.. _React: https://reactjs.org
+.. _Rubin Observatory: https://www.lsst.org
+.. _Semaphore: https://github.com/lsst-sqre/semaphore
+.. _Storybook: https://storybook.js.org/
+.. _styled-components: https://styled-components.com
+.. _Squareone repository: https://github.com/lsst-sqre/squareone

docs/dev/development-tasks.rst

@@ -0,0 +1,76 @@
+#################
+Development tasks
+#################
+
+Once you have a working development environment (see :doc:`set-up`), you can run tasks to help you develop and test the project.
+This page outlines those development tasks.
+
+Start the development server
+============================
+
+.. code-block:: sh
+
+   pnpm dev
+
+View the site at http://localhost:3000.
+This site auto-updates when running with the development server.
+
+`API routes <https://nextjs.org/docs/api-routes/introduction>`__ are accessed on ``http://localhost:3000/api/*``.
+The ``pages/api`` directory is mapped to ``/api/*``.
+Files in this directory are treated as API routes instead of React pages.
+The purpose of the ``pages/api/dev`` endpoints are to mock external services in the RSP; see the re-writes in :file:`next.config.js`.
+
+Start the Storybook server
+==========================
+
+Storybook_ is an environment for documenting and designing React components.
+You can start up Squareone's Storybook development site::
+
+.. code-block:: bash
+
+   pnpm storybook
+
+Manual linting and formatting
+-----------------------------
+
+Typically linting is run by your IDE while you develop and again when you commit code (via Husky).
+You can also manually lint and format code.
+
+Lint JavaScript via `next lint`_:
+
+.. code-block:: bash
+
+   pnpm lint
+
+Check formatting with Prettier_:
+
+.. code-block:: bash
+
+   pnpm format:check
+
+Or automatically fix files with Prettier_:
+
+.. code-block:: bash
+
+   pnpm format
+
+Create a production build
+=========================
+
+You can create a production build of the application, which can be a useful check of a process that typically runs inside the Docker image build:
+
+.. code-block:: bash
+
+   npm run build
+
+You can serve the production build locally:
+
+.. code-block:: bash
+
+   npm run serve
+
+VS Code tasks
+=============
+
+Many of these tasks are also available as VS Code tasks.
+From the VS Code command pallet run ``Tasks: Run Task`` and select the task you want to run.

docs/dev/index.rst

@@ -4,3 +4,8 @@ Developer guide
 
 This documentation will help you contribute to the Squareone code.
 If you are an admin looking to deploy and operate Squareone on the Rubin Science Platform, the :doc:`deployment guide <../deployment/index>` is the right place to start.
+
+.. toctree::
+
+   set-up
+   development-tasks