{"id":21192990,"url":"https://github.com/cloudfour/tpp-research-monorepo","last_synced_at":"2025-08-13T21:43:18.729Z","repository":{"id":38463082,"uuid":"255974811","full_name":"cloudfour/tpp-research-monorepo","owner":"cloudfour","description":null,"archived":false,"fork":false,"pushed_at":"2023-01-06T11:39:45.000Z","size":3718,"stargazers_count":5,"open_issues_count":33,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-27T09:22:12.307Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudfour.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-15T16:26:42.000Z","updated_at":"2024-03-19T22:58:08.000Z","dependencies_parsed_at":"2023-02-06T00:16:14.665Z","dependency_job_id":null,"html_url":"https://github.com/cloudfour/tpp-research-monorepo","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfour%2Ftpp-research-monorepo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfour%2Ftpp-research-monorepo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfour%2Ftpp-research-monorepo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfour%2Ftpp-research-monorepo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudfour","download_url":"https://codeload.github.com/cloudfour/tpp-research-monorepo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248764376,"owners_count":21158074,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-20T19:12:20.569Z","updated_at":"2025-04-13T18:41:13.222Z","avatar_url":"https://github.com/cloudfour.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TPP Research Monorepo\n\nThis repo is exploring translating components from native web components (Stencil.js) into front end frameworks, documentation tools, and design tools.\n\nThe goal is to show how patterns and components can be shared and reused through every step of the web publishing process. Designers, developers, and content authors can all leverage the same shared components as they work.\n\n## Developers\n\nComponents are written as web components using Stencil JS. These web components can then be easily translated into a number of frameworks and front-end environments. This repo shows how to use these components in the following contexts:\n\n- A React app\n- A Vue app\n- An Angular app\n- An Ember app\n- A vanilla JS Express app\n\n## Designers\n\nThese same components can be used in design tools allowing you to design with our prebuilt components. Currently components have only been translated to two tools:\n\n- Framer\n- UXPin Merge\n\n## Content Authors\n\nThese components can also be used to give content authors high fidelity previews of the content they're editing from within their CMS. Currently this has only been set up for Storyblok.\n\n## Documentation\n\nAll of these different stakeholders can also find information about these components in a single source of truth. The raw web components are documented in a Storybook instance.\n\n# Technical Implementation\n\nThis monorepo houses code showing how to enable all the integrations mentioned above. Most code is written using various front-end frameworks, JS, HTML, and CSS.\n\n## Local Development Approach\n\nIn the long run we'll likely want to publish a number of packages to a package registry:\n\n- Vanilla Web Components\n- React Components\n- Vue Components\n- FramerX Components\n\nIndividual projects can then easily install and reference the relevant components. However, this approach would slow down local development. For now, all files are referenced locally in between directories. A few hacks are required to make this work, but it should speed up local development.\n\n## Component Development\n\nThe core of the project is a stencil.js directory. To develop these components run the following command:\n\n```zsh\n# Navigate to the `stencil-components` directory\ncd stencil-components\n\n# Run and watch a stencil JS server\nnpm start\n```\n\n## CSS Output\n\nMost of our stencil component CSS is defined within our custom elements but a few CSS files are provided to improve the styling and allow theming of these components.\n\n- **document-styles.css** — This file applies some base styles to your document so its styles will match our component styles\n- **custom-props.css** — This file defines custom props which are referenced within the shadow DOM CSS of our custom elements.\n- **theme-example.css** — This file is an (ugly) example of overriding the custom props defined above to theme our components.\n- **utilities.css** — _Coming soon..._\n- **fonts.css** — This file loads our brand fonts. It loads a variable version as well as a non-variable fallback. Omit this file if you're using an alternate font or font loading strategy.\n\n## Fonts\n\nFor our font CSS to work our font files will need to be in the correct location in relation to the font CSS:\n\n```\n├─ css\n|  └── fonts.css\n└ fonts\n   └── source-sans-pro-latin-extendeed\n        └── font files...\n```\n\nIf you would like to load different fonts, or locate your fonts in a different location, you should omit fonts.css and add your own font loading strategy.\n\nWe recommend preloading the variable fonts. (Browsers that don't support variable fonts mostly don't support preloading so won't be affected.):\n\n```\n\u003clink\n  rel=\"preload\"\n  href=\"/assets/fonts/source-sans-pro-latin-extended/variable-italic.woff2\"\n  as=\"font\"\n  type=\"font/woff2\"\n/\u003e\n\u003clink\n  rel=\"preload\"\n  href=\"/assets/fonts/source-sans-pro-latin-extended/variable-regular.woff2\"\n  as=\"font\"\n  type=\"font/woff2\"\n/\u003e\n```\n\n## Converting Stencil Components to Other Formats\n\nThis repo is set up to export Stencil components to a variety of output targets\n\n### Building React Components\n\nThis project uses Stencil's `@stencil/react-output-target` plugin to generate React wrappers for components. Building these components is a two step process:\n\n1. Building the output of our `stencil-components` directory which adds files to our `react-components` directory\n2. Building the output of our `react-components` directory with the new files from `stencil-components`\n\n### Building Angular Components\n\nThis project uses Stencil's `@stencil/angular-output-target` plugin to generate Angular wrappers for components. Building these components is a two step process:\n\n1. Building the output of our `stencil-components` directory which adds files to our `angular-components` directory\n2. Building the output of our `angular-components` directory with the new files from `stencil-components`\n\n### Building Vue Components\n\nThis project uses Stencil's `@stencil/vue-output-target` plugin to generate Vue wrappers for components. Building these components is a two step process:\n\n1. Building the output of our `stencil-components` directory which adds files to our `vue-components` directory\n2. Building the output of our `vue-components` directory with the new files from `stencil-components`\n\n### Building All Components\n\nBefore building components you'll need to install all the component dependencies by running `npm run install:components` from the project root.(`/`). Then you can build Stencil components, convert them to React components, and populate our various apps in a single command: `npm run build:components`.\n\n## Building an Express App\n\nAfter running `npm run build:components` you can develop the Express app by running the following commands:\n\n```zsh\n# Navigate to the `express-app` directory\ncd express-app\n\n# Install dependencies\nnpm ci\n\n# Run and watch a Express server\nnpm start\n```\n\nThere's currently an issue where the app doesn't report the URL for you to visit. This should generally be http://localhost:3000/\n\n## Building a React Site\n\nOur React components are consumed by a simple React app. After building our React components you can develop this site by running the following commands:\n\n```zsh\n# Navigate to the `react-app` directory\ncd react-app\n\n# Install dependencies\nnpm ci\n\n# Run and watch a React server\nnpm start\n```\n\n## Building an Angular Site\n\nOur Angular components are consumed by a simple Angular app. After building our Angular components you can develop this site by running the following commands:\n\n```zsh\n# Navigate to the `angular-app` directory\ncd angular-app\n\n# Install dependencies\nnpm ci\n\n# Run and watch an Angular server\nnpm start\n```\n\n## Building a Vue Site\n\nOur Vue components are consumed by a simple Vue app. After building our Vue components you can develop this site by running the following commands:\n\n```zsh\n# Navigate to the `vue-app` directory\ncd vue-app\n\n# Install dependencies\nnpm ci\n\n# Run and watch a Vue server\nnpm start\n```\n\n## Building an Ember Site\n\nWe're able to use the [ember-cli-stencil](https://github.com/alexlafroscia/ember-cli-stencil) to pull Stencil components into the Ember app. However, they're still using the native component API and syntax. If you want the Ember syntax you'll need to manually wrap your web components as Ember components.\n\nLuckily, Ember works well with web components, so it doesn't take a ton of work to create wrappers. You can see some examples in our Ember app. To run the Ember app, run the following commands:\n\n```zsh\n# Navigate to the `ember-app` directory\ncd ember-app\n\n# Install dependencies\nnpm ci\n\n# Run and watch a Ember server\nnpm start\n```\n\n## Building a Svelte Site\n\nWe currently don't have an example of a Svelte site, but Stencil recently added a [Svelte output target](https://www.npmjs.com/package/@stencil/svelte-output-target) so it would be easy to automatically generate the components.\n\n## Designing with Components in FramerX\n\nFramer X allows us to import these same React components and use them in a graphical editor.\n\nEach component we want to use needs a special Framer X wrapper to allow us to import the component and interact with its props.\n\nUnfortunately there's currently an additional manual step to allow our react components to be used in Framer X.\n\nAfter building our React components, navigate to `react-components/dist/components.js` and update the following import statement:\n\n`../../stencil-components/loader` --\u003e `../../stencil-components/loader/index.cjs.js`\n\nI think there's a disconnect between TypeScript and JavaScript imports here. I'm sure there's a solution, but I haven't dug into it yet.\n\nAfter building the components and making that change you should be able to open the `components.framerfx` file in Framer X and begin designing with components.\n\n## Designing with Components in UXPin Merge\n\nFor this to work you'll need access to UXPin Merge which is in early access. Then you'll need to make the same change mentioned for Framer:\n\n`../../stencil-components/loader` --\u003e `../../stencil-components/loader/index.cjs.js`\n\nThen you should be able to UXPin merge:\n\n```zsh\n# Navigate to the `uxpin` directory\ncd uxpin\n\n# Install dependencies\nnpm ci\n\n# Run UXPin merge\nnpm start\n```\n\nIn the long term we'll explore pushing up components using CI but this works for now.\n\n## Viewing Components in Storybook\n\nThe web components are also documented in storybook. After running the `stencil-components` project, or running `npm run build:components` Storybook should\nbe ready to document these components. To launch storybook run the following\ncommands\n\n```zsh\n# Navigate to the `storybook` directory\ncd storybook\n\n# Install dependencies\nnpm ci\n\n# Run and watch a Storybook server\nnpm run storybook\n```\n\n## Editing Content in Storyblok\n\nThese components have been hooked up to a Storyblok CMS instance. These components are used to show a high fidelity preview of the rendered pages as they edit content.\n\nIn order to actually test this out you'll need to have an account with access to our Storyblok instance. You'll then add your API key to the `.env` file in the Storyblok directory, run `npm start` and load the editor at storyblok.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudfour%2Ftpp-research-monorepo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudfour%2Ftpp-research-monorepo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudfour%2Ftpp-research-monorepo/lists"}