@knapsack/app-ui NPM

Knapsack Cloud App UI

Handy Links

Vercel Deploys

Setup

Install dependencies

yarn

Make sure your setup is healthy

yarn dr

Get Account Access; if these links open, you're good:

Ensure a local .env file exists at the root of the project with at least the following content:

HASURA_ADMIN_SECRET="hasura admin secret code goes here"

Replace the value above with the x-hasura-admin-secret found within the Request Headers section of the Hasura GraphQL Explorer.

Commands

QuickStart

yarn # install deps
yarn start
# open http://localhost:8080 when you see it
# optionally open up 2nd Terminal tab and run `yarn test:watch`

Main Commands

yarn start Dev starting local work, kick off all watches & servers
- Run HMR=yes yarn start to opt-in to using Hot Module Replacement to speed up WebPack rebuilds. Note that sometimes weird state can happen that requires a browser refresh to reset. Once those scenarios are worked out, then this will become the default.
- yarn start:all to run App & Storybook
yarn sb:watch to run Storybook
yarn test:watch Get quick feedback from TypeScript, Eslint, and other semi-quick running tests (i.e. no Cypress tests)
yarn dr Run Doctor to check your setup
yarn new Scaffold out new files using Plop. Config in plopfile.ts.
yarn fix Auto-fix codes
yarn reset Clean all built code, toast & re-install node_modules

Other Commands

yarn wp:stats Run to find out why your Webpack bundle is so big! Runs a clean prod build, then opens up ./public/stats.html

Getting Started

Follow the "Setup" steps above
Run yarn start - be patient, read all the terminal output & wait for http://localhost:8080 to say it's ready, you have two options on opening your browser:
1. Just open http://localhost:8080
2. In VS Code, ensure you have the Debugger for Chrome extension, then:
  1. In main menu click "View > Run"
  2. In top left's "Run" menu select either "Launch Chrome" or "Launch Chrome Canary"
  3. In any .tsx or .ts file in VS Code you can now create breakpoints that will allow rich runtime information about variables and more that can be triggered when navigated to in Chrome.
  4. To configure, adjust .vscode/launch.json. More help here
When you first open http://localhost:8080 it might take just a bit the first time since we're using webpack-dev-server and HTTP requests trigger in-memory Webpack compiling; this makes re-compiles much faster though since it's in-memory & doesn't write to disk! PS That's why nothing is in ./public until yarn build
Open your dev tools, make sure you can see the console and pay attention to what it says - if it says something is wrong, then fix it. Devs should be intentional about their use of console.log, console.warn, console.error (can fail Cypress tests), & console.debug <== Use the last one all you want; that can be messy & noisy.
You've probably opened your browser to the url path / or /ks, if that's confusing, open the Bootstrap Demo by going to /site/ks-demo-bootstrap/latest
To get lint & type test feedback as you code, do one of the following:
1. Run yarn test:watch in a new Terminal tab
2. In VS Code's menu select "Terminal > Run Task...", then select "Tests watch". This will:
  1. Run yarn test:watch in VS Code's terminal
  2. Fill out the "Problems" panel with results. This is convenient b/c you can click on the individual problems to go right to them.

Conventions

Ideally conventions are enforced through lint rules or tests, if not then they are listed here:

Prefer named exports over export default - unless you want to use it in React.lazy()
Functions should only take a single parameter, use an object to pass in more than 1 var

Knapsack Demo Sites

ks-demo-bootstrap - https://github.com/knapsack-cloud/ks-demo-bootstrap

Getting client side data

Redux Store

import { useSelector } from '@ks-app/app';

const MyComponent = () => {
  // Autocompletion is your friend for accessing items in the datastore
  const title = useSelector((s) => s?.settingsState?.settings?.title);

  return <div>The title: {title}</div>;
};

Knapsack Cloud GraphQL DB

View the data and use the Graphiql playground by going to https://db.knapsack.cloud - you'll be asked for the Admin Secret, which can be found inside your .env file (run yarn vc:env-pull if it's not found).

Start by either adding to or creating a my-data.gql file inside the ./src directory with something like:

query MyCustomData {
  sites {
    id
    title
  }
}

query MySingleSite($siteId: String!) {
  sites_by_pk(id: $siteId) {
    title
  }
}

Run yarn gql:build (taken care of for you during yarn start) and you'll notice that the file my-data.gql.generated.tsx was made right next to it. Import and use the custom Apollo useQuery hooks functions inside:

import {
  useMyCustomDataQuery,
  useMySingleSiteQuery,
} from './my-data.gql.generated';

const MyComponent = () => {
  const { loading, data, error } = useMyCustomDataQuery();
  const { data: singleSiteData } = useMySingleSiteQuery({
    variables: {
      siteId: 'my-site-id',
    },
  });

  const singlSiteTitle = singleSiteData?.sites_by_ok?.title;

  return (
    <ul>
      {data.sites.map((site) => (
        <li key={site.id}>{site.title}</li>
      ))}
    </ul>
  );
};

Front End

Storybook (Obsolete)

yarn sb:watch to run Storybook
On any deployed site, go to /storybook to view, for example: https://next.app.knapsack.cloud/storybook
Any file ending in *.stories.tsx is pulled in by Storybook
To easily create a new story, run yarn new story ./path/to/component.tsx
- That template can be adjusted by editing ./scripts/plop/stories.tsx.hbs
Storybook configuration files are found in ./.storybook/