{"id":28050617,"url":"https://github.com/carcutter/cars-webplayer-js","last_synced_at":"2026-02-10T18:10:13.884Z","repository":{"id":279742981,"uuid":"818190288","full_name":"carcutter/cars-webplayer-js","owner":"carcutter","description":"WebPlayer, a framework-agnostic web component that seamlessly integrates CarCutter’s immersive car showrooms into any website. This decision reflects our dedication to transparency, collaboration, and innovation in automotive retail marketing.","archived":false,"fork":false,"pushed_at":"2025-04-29T15:19:51.000Z","size":4726,"stargazers_count":19,"open_issues_count":3,"forks_count":2,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2025-04-29T15:23:42.164Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://carcutter.github.io/cars-webplayer-js/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carcutter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-06-21T09:42:29.000Z","updated_at":"2025-04-29T15:12:19.000Z","dependencies_parsed_at":"2025-04-29T15:22:07.664Z","dependency_job_id":"4426b6f2-7d52-4af5-be1b-a9eafcea667f","html_url":"https://github.com/carcutter/cars-webplayer-js","commit_stats":null,"previous_names":["carcutter/cars-webplayer-js"],"tags_count":77,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carcutter%2Fcars-webplayer-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carcutter%2Fcars-webplayer-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carcutter%2Fcars-webplayer-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carcutter%2Fcars-webplayer-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carcutter","download_url":"https://codeload.github.com/carcutter/cars-webplayer-js/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253655916,"owners_count":21943072,"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":"2025-05-12T00:36:46.614Z","updated_at":"2026-02-10T18:10:13.877Z","avatar_url":"https://github.com/carcutter.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Lint Commit Messages](https://github.com/carcutter/cars-webplayer-js/actions/workflows/lint_commits.yml/badge.svg)](https://github.com/carcutter/cars-webplayer-js/actions/workflows/lint_commits.yml) [![Continuous Delivery](https://github.com/carcutter/cars-webplayer-js/actions/workflows/continuous_delivery.yml/badge.svg)](https://github.com/carcutter/cars-webplayer-js/actions/workflows/continuous_delivery.yml) [![Continuous Deployment](https://github.com/carcutter/cars-webplayer-js/actions/workflows/continuous_deployment.yml/badge.svg)](https://github.com/carcutter/cars-webplayer-js/actions/workflows/continuous_deployment.yml) [![Continuous Integration](https://github.com/carcutter/cars-webplayer-js/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/carcutter/cars-webplayer-js/actions/workflows/continuous_integration.yml)\n\n# Car-Cutter WebPlayer Monorepo\n\nThis monorepo hosts the WebPlayer project, which includes multiple demo applications and several packages for different web technologies. The project is structured to support various frameworks and libraries, enabling reusable components and configurations.\n\n## Contributing\n\n### Structure\n\nThe structure of this monorepo is organized as follows:\n\n```bash\nCARS-WEBPLAYER/\n├── apps/                    # Demo applications for different frameworks\n│   ├── demo-next/           # Demo app using Next.js\n│   ├── demo-vanilla/        # Demo app using Vanilla JS\n│   .\n│   .\n├── packages/                # Shared packages for different frameworks\n│   ├── core/                # Core logic for the web player (Composition typing, utils functions, ...)\n│   ├── core-ui/             # WebPlayer implementation (carrousel, 360, hotspots, ...)\n│   ├── core-wc/             # Wraps the WebPlayer in a WebComponent\n│   ├── webplayer-react/     # Adapt the WC WebPlayer for React\n│   ├── webplayer-next/      # Adapt the WC WebPlayer for Next.js\n│   ├── webplayer-wc/        # Expose the WC from core-wc and add React \u0026 ReactDOM\n│   .\n│   .\n└── schemas/                 # JSON schemas\n```\n\n- **apps/**: Contains demo applications showcasing the usage of the web player in various frameworks. Each demo is isolated, allowing you to see how the web player can be integrated into different environments.\n\n- **packages/**: This directory all NPM packages\n\n## Development\n\n### Setup\n\n1. Install Node v20. Tutorial for macOS [here](https://sukiphan.medium.com/how-to-install-nvm-node-version-manager-on-macos-d9fe432cc7db)\n2. Install Yarn v1 : `brew install yarn`.\n3. Install the node modules with the command `yarn`.\n\n### Developing the WebPlayer Core\n\nSimply run `yarn dev` from the workspace root to start the app in development mode.\n\n#### Using Local Composition\n\nVite serves all assets in the `/public` directory at the root path `/` during development. For instance, `/public/composition_mock.json` can be accessed at `/composition_mock.json`. Use that URL as the `compositionUrl`.\n\n### Developing the Documentation\n\nSimply run `yarn dev:docs` from the workspace root to start the documentation in development mode.\n\n### Building\n\nRun `yarn build` to build all packages\n\n#### Analyze Bundle Size\n\nGo in any package and run `yarn analyze` to analyze the bundle.\n\nNOTE : the sourcemap seems to interfere with size calculation [GitHub issue](https://github.com/KusStar/vite-bundle-visualizer/issues/8). More info [here](https://www.npmjs.com/package/vite-bundle-visualizer).\n\n### Linting\n\nRun `yarn lint`\n\n### Run demos\n\nRun `yarn demo:XX` to start any demo app\n\n## Publication\n\nThis repository uses the Changesets CLI to handle versioning and publication to NPM registry. Follow the steps below to publish new versions of your packages:\n\n### 1. Create a Changeset\n\nTo propose a new version for one or more packages, you need to create a changeset. Run the command `yarn version:commit` and follow the prompts.\n\nYou will be prompted to select the packages that should be affected and to specify the type of change (patch, minor, or major). This will create a changeset file that describes the changes.\n\n### 2. Version Packages\n\nOnce changesets have been added and merged into your base branch (e.g., `main`), you can version the packages. This step updates the version numbers in your `package.json` files and generates changelogs based on your changesets: `yarn version:apply`\n\nThis command will:\n\n- Update the version numbers in the affected `package.json` files.\n- Generate or update changelog files.\n- Prepare the packages for publishing.\n\n### 3. Ensure every thing is working as expected\n\nRun `yarn ci` to run both `build` and `lint` commands. It will also run `yarn` to be sure dependencies are correct.\n\n_NOTE: at this point, if you see a change in the yarn.lock file, it is certainly because all version have not been properly updated._\n\n### 4. Publish to npm\n\nAfter versioning the packages, you can publish them to npm. This command will publish all packages that have changed since the last release: `yarn publish:packages`\n\nMake sure you are logged in to npm with the correct credentials before running this command. The packages will be published according to the access level specified in your `changesets` configuration (`config.json`).\n\n### 5. Publish documentation\n\nRun `yarn publish:docs`\n\n## Use the WebPlayer on your App\n\n### Properties\n\n| Prop                          | Type                               | Default           | Description                                                                                                                                      |\n| ----------------------------- | ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `compositionUrl`              | `string`                           | ❌ Required       | URL to the composition data                                                                                                                      |\n| `hideCategoriesNav`           | `boolean`                          | `false`           | Hide the category-based navigation. Categories include `360`, `next360` (NextGen 360), `interior-360`, and custom ids.                            |\n| `infiniteCarrousel`           | `boolean`                          | `false`           | Allow to navigate from 1st to last media (and vice versa)                                                                                        |\n| `permanentGallery`            | `boolean`                          | `false`           | Display gallery under the carrousel                                                                                                              |\n| `mediaLoadStrategy`           | `\"quality\"`/`\"balanced\"`/`\"speed\"` | `\"quality\"`       | Strategy for loading medias.                                                                                                                     |\n| `minMediaWidth`               | `number`                           | `0`               | Force minimum media width (in pixels)                                                                                                            |\n| `maxMediaWidth`               | `number`                           | `Infinity`        | Force maximum media width (in pixels)                                                                                                            |\n| `preloadRange`                | `number`                           | `1`               | Number of items to preload before and after the viewport                                                                                         |\n| `autoLoad360`                 | `boolean`                          | `false`           | Load 360 images without having to click                                                                                                          |\n| `autoLoadInterior360`         | `boolean`                          | `false`           | Load interior 360 images without having to click                                                                                                 |\n| `categoriesFilter`            | `string`                           | `*`               | Only display certain categories                                                                                                                  |\n| `extendBehavior`              | `\"full_screen\"`/`\"event\"`/`\"none\"` | `\"full_screen\"`   | Handle extend mode                                                                                                                               |\n| `eventPrefix`                 | `string`                           | `\"cc-webplayer:\"` | Prefix of cc-player events                                                                                                                       |\n| `demoSpin`                    | `boolean`                          | `false`           | Run a spin once the 360 images has been loaded                                                                                                   |\n| `reverse360`                  | `boolean`                          | `false`           | Reverse the 360-degree rotation                                                                                                                  |\n| `integration`                 | `boolean`                          | `false`           | Allows to use maxItemsShown and disables permanentGallery with infiniteCarrousel, enables hideCategoriesNav                                      |\n| `maxItemsShown`               | `number`                           | `1`               | Maximum number of items to display in the gallery                                                                                                |\n| `analyticsEventPrefix`        | `string`                           | `cc-analytics`    | Prefix of cc-analytics events                                                                                                                    |\n| `analyticsUrl`                | `string`                           | ``                | A URL to send simple tracking / analytic events                                                                                                  |\n| `analyticsBearer`             | `string`                           | ``                | A Bearer token to authenticate when sending requests to `analyticUrl`                                                                            |\n| `analyticsSimpleRequestsOnly` | `boolean`                          | `false`           | A flag if only Simple-Requests should be sent. Will disable `analyticsBearer`. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS |\n| `analyticsDryRun`             | `boolean`                          | `false`           | A flag if the tracking / analytic events should be just output to the console instead of actually send to the `analyticsUrl`                     |\n| `analyticsDebug`              | `boolean`                          | `false`           | A flag if the tracking / analytic events should output debug information to the console                                                          |\n\n_NOTE: If you are using the WebComponent directly, you need to transform the props to HTML attributes\n(which are in dashed-case and take `string` as value type)_\n\n### Customization\n\n#### CSS\n\nYou can customize the WebPlayer CSS with CSS Variables\n\n| CSS Variable                           | Description                        | Default Value               |\n| -------------------------------------- | ---------------------------------- | --------------------------- |\n| `--cc-webplayer-background`            | Background color (contrast texts)  | `0 0% 100%`                 |\n| `--cc-webplayer-foreground`            | Foreground color (text color)      | `240 10% 3.9%`              |\n| `--cc-webplayer-primary`               | Primary color (buttons)            | `216 100% 52%`              |\n| `--cc-webplayer-primary-foreground`    | Foreground color for primary items | `--cc-webplayer-background` |\n| `--cc-webplayer-primary-light`         | Alternative to primary if too dark | `--cc-webplayer-primary`    |\n| `--cc-webplayer-neutral`               | Neutral color                      | `0 0% 39%`                  |\n| `--cc-webplayer-neutral-foreground`    | Foreground color for neutral items | `--cc-webplayer-foreground` |\n| `--cc-webplayer-hotspot-damage-color`  | Color for damage hotspots          | `37 89% 52%`                |\n| `--cc-webplayer-hotspot-feature-color` | Color for feature hotspots         | `--cc-primary`              |\n| `--cc-webplayer-radius-ui`             | UI element Border radius (buttons) | `16px`                      |\n| `--cc-webplayer-radius-carrousel`      | Carrousel border radius            | `0`                         |\n| `--cc-webplayer-radius-gallery`        | Gallery medias border radius       | `0`                         |\n\n### More customization\n\nFor more customization, take a look at the **[Online Documentation](https://carcutter.github.io/cars-webplayer-js/)**\n\n## Useful scripts\n\nScripts are available in the `scripts` directory\n\n### Generate JSON schema\n\nUse the command `yarn migrate_composition \u003cCOMPOSITION_V1_PATH\u003e`. It will create a new file with the new type\n\n### Convert composition from V2 to V3\n\nUse the command `yarn generate_json_schema`. It will create a file within the _schemas_ folder\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarcutter%2Fcars-webplayer-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarcutter%2Fcars-webplayer-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarcutter%2Fcars-webplayer-js/lists"}