Installable Kit

These components can be previewed at https://storybook.vestaboard.com

Build-time configuration (service URLs)

Host apps must inject Vestaboard service base URLs at webpack/build time (via DefinePlugin, environment, etc.). Values are read from process.env when the bundle is built—not at runtime from PHP or server .env unless your build step loads those into the webpack process.

Env vars (monorepo config/.env.*)

| Variable | Used for | | -------------------------- | ---------------------------------------------------------------------------------------- | | PLATFORM_ENDPOINT | Platform REST, subscription config token, media upload, deeplinks, visual editor session | | MESSAGE_SERVICE_ENDPOINT | Message service favorites (add/remove) | | VESTABOARD_API_ENDPOINT | GraphQL (share message, JWT exchange) | | APP_ENDPOINT | Web app links (e.g. board simulator) |

Run yarn env:prod / yarn env:staging (or copy the matching config/.env.* to root .env) before building so webpack sees these values in process.env.

Blank or whitespace-only env values are skipped (the next name in the precedence list is used).

Backwards-compatible env aliases

| Monorepo var | Legacy alias | | -------------------------- | ---------------------- | | PLATFORM_ENDPOINT | V1_PLATFORM_ENDPOINT | | MESSAGE_SERVICE_ENDPOINT | V2_MESSAGE_ENDPOINT |

Exports PLATFORM_ENDPOINT and V2_MESSAGE_ENDPOINT remain available as resolved constants for existing imports. Deeplink and API paths should use platformHttpUrl() / platformWsUrl() so trailing slashes on the base URL are handled consistently.

Example (webpack)

Pass monorepo env vars through at build time:

new webpack.DefinePlugin({
  'process.env.PLATFORM_ENDPOINT': JSON.stringify(
    process.env.PLATFORM_ENDPOINT || 'https://platform.vestaboard.com',
  ),
  'process.env.MESSAGE_SERVICE_ENDPOINT': JSON.stringify(
    process.env.MESSAGE_SERVICE_ENDPOINT ||
      'https://message-service.vestaboard.com',
  ),
  'process.env.VESTABOARD_API_ENDPOINT': JSON.stringify(
    process.env.VESTABOARD_API_ENDPOINT || 'https://api.vestaboard.com',
  ),
  'process.env.APP_ENDPOINT': JSON.stringify(
    process.env.APP_ENDPOINT || 'https://web.vestaboard.com',
  ),
})

Installation

The current version of Installable kit requires these peer dependencies to be installed in your project:

{
  "peerDependencies": {
    "@mui/icons-material": "^5.11.13",
    "@mui/material": "^5.11.13",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

With those in place, just run:

yarn @vestaboard/installables

or

npm install @vestaboard/installables

Available Scripts

In the project directory, you can run:

yarn start

Opens storybook and allows you to view and edit the components

yarn test

Runs the tests using jest

yarn build

Builds the typescript files

Releasing a new version

For a new version release, just bump the patch "version" number in package.json. This will trigger the publish job during CI, when merged into main.

ex:

maj.min.patch
4.0.0 => 4.0.1

git switch -c feature/my-changes
git add --all
git commit -m "changed _ components css"
git push
# make a PR to main, and the new changes will be deployed when reviewed and merged

PRs should be made targeting the default branch

feature/my-changes => main

Migrating away from @mui/styles makeStyles, use MUI System or SX prop

@mui/styles deprecation notice

# Old ❌ installable kit < 3.0.46
import { makeStyles } from '@mui/styles';

const useStyles = makeStyles({
  button: (props) => ({
    padding: 4,
    marginLeft: 4,
    borderRadius:  6
  })
})
...
<Button className={classes.button}/>

# New ✅ ^4.0.0
import { makeVestaboardStyles } from '@vestaboard/installables/lib/hooks/useVestaboardStyles';

const useVestaboardStyles = makeVestaboardStyles((props) => ({
  button: {
    // have to specify unit type now
    padding: '4px',
    marginLeft: '4px',
    borderRadius: '6px'
  }
}))
// or w/o props
const useVestaboardStyles = makeVestaboardStyles({
  button: {
    // have to specify unit type now
    padding: '4px',
    marginLeft: '4px',
    borderRadius: '6px'
  }
})
...
<Button sx={classes.button}/>