{"id":26234907,"url":"https://github.com/flowpack/media-ui","last_synced_at":"2026-02-27T09:58:08.828Z","repository":{"id":40484896,"uuid":"215841568","full_name":"Flowpack/media-ui","owner":"Flowpack","description":"The development repository for the new Neos media management interface","archived":false,"fork":false,"pushed_at":"2024-10-29T08:24:31.000Z","size":28102,"stargazers_count":21,"open_issues_count":60,"forks_count":16,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-10-29T09:39:12.681Z","etag":null,"topics":["graphql","hacktoberfest","neos-cms"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Flowpack.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":"https://shop.neos.io/neosfunding/onetime-badges/"}},"created_at":"2019-10-17T16:49:35.000Z","updated_at":"2024-10-29T08:19:21.000Z","dependencies_parsed_at":"2023-11-03T09:36:44.154Z","dependency_job_id":"387f5201-3918-460c-88da-83a9e3241350","html_url":"https://github.com/Flowpack/media-ui","commit_stats":{"total_commits":509,"total_committers":13,"mean_commits":39.15384615384615,"dds":0.1905697445972495,"last_synced_commit":"87c1622924e911485e7b2e9d0813560176e2dd65"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Flowpack%2Fmedia-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Flowpack%2Fmedia-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Flowpack%2Fmedia-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Flowpack%2Fmedia-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Flowpack","download_url":"https://codeload.github.com/Flowpack/media-ui/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247386262,"owners_count":20930619,"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":["graphql","hacktoberfest","neos-cms"],"created_at":"2025-03-13T02:29:57.605Z","updated_at":"2026-02-27T09:58:08.822Z","avatar_url":"https://github.com/Flowpack.png","language":"TypeScript","funding_links":["https://shop.neos.io/neosfunding/onetime-badges/"],"categories":[],"sub_categories":[],"readme":"Neos Media UI\n-------------\n\nThis package contains the new interface to manage media in Neos CMS (7.3 - 8.3).\n\nDuring the initial development the package will be in the Flowpack namespace and will\nlater replace `neos/media-browser`.\n\nIf you want to use Neos, please have a look at the [Neos documentation](http://neos.readthedocs.org/en/stable/).\n\n## Screenshots\n\n### Asset management\n\n### Asset selection\n\n### Asset details\n\n## Installation\n\nRun the following command to install it:\n\n```console\ncomposer require flowpack/media-ui\n``` \n\nAfterward you should execute doctrine migrations, as the package adds new columns to the database:\n\n```console\n./flow doctrine:migrate\n```\n\nIn some rare cases it's necessary to flush the caches to prevent errors PHP errors, as the package extends some core classes:\n\n```console\n./flow flow:cache:flush\n```\n\nThen you should update the paths of existing asset collections:\n\n```console\n./flow assetcollections:updatepaths\n```\n\nThis is only necessary once after the installation. Afterward the paths will be updated automatically.\n    \n### What changes?\n\nThis package will currently add a second media backend module called `Media (new)` and a new \nmedia selection screen for asset and image editors.\nThe old media module will still be available until this package replaces it completely with a later, major\nrelease of Neos.\n\n#### Disabling the old Media module\n\nIf you don't need the old Media module, you can disable it in `Settings.yaml`:\n\n```yaml\nNeos:\n  Neos:\n    modules:\n      management:\n        submodules:\n          media:\n            # Disable the default media module and use the new media ui\n            enabled: false\n          mediaui:\n            # Moves the new module to top\n            position: start\n```\n    \n#### Disabling the new media selection\n\nIf you want to use this package in a real project you might want to \ndisable the new media selection if it doesn't work as expected.\nYou can do this by adding the following setting to your `Settings.yaml`:\n          \n```yaml\nNeos:\n  Neos:\n    Ui:\n      frontendConfiguration:\n        Flowpack.Media.Ui:\n          useNewMediaSelection: false\n``` \n\n#### Privileges\n\nBy default any editor (Neos.Neos:AbstractEditor) can access the new media module and manage assets, tags and collections.\n\nTo adjust the privileges you can use the following privilege targets for any role:\n\n```yaml\n- privilegeTarget: 'Flowpack.Media.Ui:ManageAssets'\n  permission: GRANT\n- privilegeTarget: 'Flowpack.Media.Ui:ManageTags'\n  permission: GRANT\n- privilegeTarget: 'Flowpack.Media.Ui:ManageAssetCollections'\n  permission: GRANT\n```\n\n#### Hierarchical asset collections\n\nThis package will enable a hierarchical asset collection structure via AOP (until the feature is in the Neos core).\nWith this feature you can add a collection in another collection or assign existing ones to another and\nthis way create a structure comparable with folders in your computer's file system.\n\nIt is recommended to enable the feature flag `limitToSingleAssetCollectionPerAsset` (see below) for a better experience - \nsee below. \n\nThe package also provides the `\\Flowpack\\Media\\Ui\\Security\\Authorization\\Privilege\\ReadHierarchicalAssetCollectionPrivilege` \nwith the additional method `isInPath(\u003cstring\u003e)`, which can be used to control access to the collections.\n\n```yaml\nprivilegeTargets:\n  'Flowpack\\Media\\Ui\\Security\\Authorization\\Privilege\\ReadHierarchicalAssetCollectionPrivilege':\n    'Some.Package:ReadSpecialAssetCollectionAndSubCollections':\n      matcher: 'isInPath(\"/important-collections\")'\n  'Flowpack\\Media\\Ui\\Security\\Authorization\\Privilege\\ReadAssetPrivilege':\n    'Some.Package:ReadSpecialAssets':\n      matcher: 'isInCollectionPath(\"/important-collections\")'\n```\n\n## Optional features\n\n### Limit assets to be only assigned to one AssetCollection\n\nBy limiting assets to only be in one collection you can enforce a more folder-like experience:\n\n```yaml\nNeos:\n  Neos:\n    Ui:\n      frontendConfiguration:\n        Flowpack.Media.Ui:\n          # Only allow a single asset collection selection per asset to treat collection like folders\n          limitToSingleAssetCollectionPerAsset: true\n```\n\n### Fast asset usage calculation \u0026 unused assets view\n           \nThe default asset usage in Neos is very slow as it is calculated when at runtime. For that it checks \nyour whole project where an asset might be used. For the new Media UI, a new method has been implemented via the package \n[Flowpack.Neos.AssetUsage](https://github.com/Flowpack/Flowpack.Neos.AssetUsage).\n\nThe package provides a service that stores all asset usage references in a database table (other storages can be implemented).\nAfter installing the package and its peer dependencies, you should therefore update the usage reference index:\n\n    ./flow assetusage:update\n\nYou have to do this only once for each instance of the application, f.e. dev / staging / production. \nAfterwards the index will automatically be kept up-to-date. Make sure you run the command manually again after you run imports or\nchange the content repository in any other unusual way. This will clean up any outdated usage.\n                                                                                \nYou can now enable the feature via the following setting:\n\n```yaml\nNeos:\n  Neos:\n    Ui:\n      frontendConfiguration:\n        Flowpack.Media.Ui:\n          queryAssetUsage: true\n```\n\nNow the \"delete\" action for assets will be disabled if an asset is in use, and the filter dropdown contains a new item \"Unused\". \nSelecting it will switch the main view to show all unused assets.\n\n### Customise usage details\n\nThe usage calculation mechanism in Neos already supports custom usage providers via the `AssetUsageStrategyInterface`.\nIf your strategy implements this interface, the Media UI will show the usages separately for each strategy.\n\nBy also implementing the `UsageDetailsProviderInterface` you can provide a custom label for the strategy\nand also custom headers and values for each entry.\n\n### Show similar assets\n\nThis package provides a `SimilarAssetStrategyInterface`. \nOther packages can implement this interface and provide a list of\nother assets based on a given asset.\n\nExample for this could be perceptually similar images or assets with similar filenames.\n\nGiven that you installed a package with a strategy, enable the feature in the ui with the following setting:\n\n```yaml\nNeos:\n  Neos:\n    Ui:\n      frontendConfiguration:\n        Flowpack.Media.Ui:\n          showSimilarAssets: true\n```\n\n### Disable asset redirect checkbox\n\nIf you don't want to or can't use the automatic generation of redirects for assets, you can disable it with the following setting:\n\n```yaml\nNeos:\n  Neos:\n    Ui:\n      frontendConfiguration:\n        Flowpack.Media.Ui:\n          createAssetRedirectsOption: false\n```\n    \n## Architecture\n\n### API / GraphQL\n\nThis module introduces a GraphQL API for the Neos Media system.\nThe API is open and can be reused for custom apps. A valid Neos backend user is required to access it,\nbut you can define custom policies and an authentication provider to allow access without a user \nand f.e. use a token based authentication.\n\n#### Schema\n\nThe GraphQL schema can be found [here](Resources/Private/GraphQL/schema.root.graphql). \n\n### Interface\n\nThis module uses React for the implementation of the UI. Currently, most parts of the application are implemented\nas feature based packages in the `packages` folder.\nIn future releases the code will be further split into smaller packages.\n\n### State management\n\n#### Query variables\n\nQuery related state variables are stored via GraphQL Mutations in the Apollo Client Cache.\nSome of those variables are then persisted into the localstorage of the browser.\n\n#### Resolved query result state\n\nThe MediaUI provider currently stores the results in its state and provides them to\nall child components via provider values.\nThis will probably be changed to only set shared states that all components can access.\n\n#### Component states\n\nComponent state should be stored with React hooks.\n\n#### Shared component states\n\nThe shared component states are current implemented via React [Recoil](https://recoiljs.org) atoms and selectors.\nSee the `state` folders in the various modules in `packages` for examples.\n\nThose should be used every time multiple components share a state that is not relevant for\nthe GraphQL queries.\n\n## Fund the development\n\nWe need your help to develop this package. You can find supporter badges on the official [Neos funding site](https://shop.neos.io/neosfunding/onetime-badges/).\n\n## Contributing\n\nTo start with development, make sure you have `nvm` and `yarn` installed and run the following command in the package's folder:\n\n```console\nyarn\n```\n    \n### Running the standalone dev server without Neos\n\nThe dev server allows to run the module without a Neos instance.\nThis is also the basis for running most tests and implementing new features.\n\n```console\nyarn dev\n```\n    \nEnter `localhost:8000` in your browser, and you will have a running media ui instance without Neos.\n\n### Building the module assets\n\nThis will create a production build of the module assets.\n\n```console\nyarn build\n```\n    \n### Recompile files during development\n\nThe following command will recompile and reload the media module when changes to the scripts happen:\n\n```console\nyarn watch\n```\n    \n#### Only watch the backend module code\n\n```console\nyarn watch:module\n```\n    \n#### Only watch the UI plugin\n\n```console\nyarn watch:editor\n```\n\n### Check for code quality\n\nRun the following command to verify the TypeScript files:\n\n```console\nyarn lint\n```\n    \n### Run e2e tests\n\nFirst start the dev server via `yarn dev` and the run the following command to execute all end-to-end tests: \n\n```console\nyarn e2e\n```    \n\nThe test configuration is defined in `.testcaferc.json`.\n\nTo use a different browser, you can define it when running the tests:\n\n```console\nyarn test firefox\n```\n\nCheck out the [Testcafe documentation](https://testcafe.io/documentation/402828/guides/intermediate-guides/browsers#browser-support) for more information and supported browsers.\n\n### Run phpstan for codestyle checks\n\nFirst, make sure you have [phpstan](https://phpstan.org) installed.\n\nIf the package is installed in a Neos distribution:\n\n```console\ncomposer run codestyle\n```\n    \nIf the package is standalone\n\n```console\ncomposer run codestyle:ci\n``` \n\n### Run PHPUnit for unit tests\n\nIf the package is installed in a Neos distribution:\n\n```console\ncomposer run test\n```\n    \nIf the package is standalone\n\n```console\ncomposer run test:ci\n``` \n    \n### Other development hints\n\n#### Before you commit\n\nPlease don't add the compiled frontend assets to your commits/PRs.\n\nWe will build the assets when a new release is due.\n\nIf you want to build the assets for a release, use the following command to prevent cache issues:\n\n```console\nyarn build:no-cache\n```\n\n#### Register additional icons\n\nFont Awesome icons are registered in `packages/src/lib/FontAwesome`.\nThis way the bundle size is kept to a minimum.\n\n#### Patches\n\nSeveral [patches](.yarn/patches) are applied during installation via [patch-package](https://github.com/ds300/patch-package).\nAdditional patches can be generated and stored there with the same tool if necessary.\n\n#### Connection between the backend module and UI plugin\n\nThe codebase is 99% reused between the backend module and the asset selection in the Neos UI.\nMake sure changes work in both worlds or provide a compatibility layer in the corresponding initialisation.\n    \n### Development helpers\n\n* [Extension](https://github.com/apollographql/apollo-client-devtools) for debugging GraphQL schema and queries in the browser\n* [Plugin](https://plugins.jetbrains.com/plugin/8097-js-graphql) for code completion and helpers in PHPStorm\n\n## License\n\nSee [license](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflowpack%2Fmedia-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflowpack%2Fmedia-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflowpack%2Fmedia-ui/lists"}