@planningcenter/doxy-web

doxy-web

Unified styles for Church Center Web.

Links

• NPM package
• Github repository
• Storybook (documentation)

Getting Started

cd Code
git clone [e-mail]:planningcenter/doxy-web.git
cd doxy-web
yarn install

Contributing Guide

• make changes in branched forked from main
• release candidate package versions can be created from any branch (see below) and used for testing on staging (following -rc.0 naming conventions)
• because main has branch protection, final version updates to the NPM package should published from your feature branch as the last commit before the approved PR is merged.

Development Scripts:

💅 Making SCSS changes:

• yarn link (in doxy-web)
• yarn link @planningcenter/doxy-web (in church-center or proxied app)
• yarn install (in church-center or proxied app)
• yarn develop (in doxy-web): listens for SCSS changes and compiles to CSS
• changes reflected in CCW for local testing

⚠️ run yarn unlink @planningcenter/doxy-web and yarn install --check-files to return package to published version from NPM

🚧 Local development in products with yalc

If you are working on a new feature or run into a specific bug in your product, you can use yalc to install and run the Doxy Web package locally. ✨

1. Install yalc globally

   yarn global add yalc
   

2. Navigate to the root doxy-web folder and run the below command to watch for changes and publish them to the local yalc registry.

   cd ~/Code/doxy-web
   yarn develop:yalc
   

3. Navigate to the product you want to use the local Doxy Web version in and run the following commands.

   cd ~/Code/YOUR_PRODUCT
   yalc add @planningcenter/doxy-web && yarn install
   

4. If you are using Rails with Webpacker and would like to watch for changes when a new version is published to the yalc registry, add this to your config/webpacker.yml file.

   resolved_paths: [".yalc"]
   

Troubleshooting & Best Practices

• If the Doxy Web library fails to publish in step 2, you can stop the server and publish the local package manually.

  cd ~/Code/doxy-web
  yalc publish --push
  

• If you see Module not found: Error: Can't resolve package-name after step 3, try the following commands in your product.

  rm -rf node_modules
  yarn install
  

  • To make sure that you don't commit yalc changes to your package.json file, you can add this git hook to YOUR_PRODUCT/.git/hooks/pre-commit:

  if which yalc; then
    yalc check
  fi
  

• Alternatively, you can add .yalc and yalc.lock to your .gitignore file. If you do, be sure to run yalc remove before committing package manifest changes.

  echo '.yalc' >> .gitignore
  echo 'yalc.lock' >> .gitignore
  

⚛️ Making component changes:

• yarn start opens Storybook (compiles SCSS, Hot Module Reloading, etc)
  • local pco-box: http://localhost:3000
  • pco-cloud-box: https://churchcenter.test:3000
• yarn build compiles SCSS & JS modules using Rollup

⚠️ SCSS/JS changes reflected in Storybook are not available in CCW without running yarn build or yarn develop

🚀🤞 Publishing prerelease version to NPM:

• commit changes
• npm login
• yarn prerelease
• in CLI, choose prerelease if the version shown follows our Planning Center release strategy. If not, choose other and manually add the version. (For example, if the final version will be 1.19.0, the first alpha version would be 1.19.0-rc.0)
• after alpha version is published, run yarn add @planningcenter/doxy-web@next in church-center or proxied app

🚢📦 Deploying package to NPM (before merging PR):

• npm login
• yarn deploy:package
• in CLI tool, choose semantic version to reflect level of changes made:

v1.2.3
 ^ ^ ^
 │ │ └─ Patch: Documentation and fixes
 │ └─── Minor: Additions
 └───── Major: Deletions and edits

• add version/change description on Github and create new release (page will open automatically in browser after deployment is complete)
• if updating church-center or proxied apps, update VERSIONS.md to reflect the change/associated PR

🚀📚 Deploying Storybook:

• yarn deploy:storybook
• view changes: https://planningcenter.github.io/doxy-web/

Consumable CSS

• yarn add @planningcenter/doxy-web
• import @planningcenter/doxy-web/dist/css/doxy-web