Come together with the global Drupal community in Rotterdam, 28 Sept – 1 Oct 2026. Sessions, contribution, connection, and Early Bird savings until 8 June.Problem/Motivation
Once #3340712: Add Single Directory Components as a new experimental module has landed this issue will track the necessary work to get the module to beta and then a stable state.
Docs: https://www.drupal.org/docs/develop/theming-drupal/using-single-director...
Proposed resolution
Current status
- Currently (as of Drupal 10.0.x), Single Directory Components is proposed for core inclusion with experimental status and located in core/modules/sdc.
- Issues with SDC are still tracked and addressed in https://www.drupal.org/project/sdc first, then carried to the open MR.
- Drupal 10.1's first alpha release is scheduled for the week of Week of April 24, 2023. We are hoping to get #3340712: Add Single Directory Components as a new experimental module merged before that.
- Consensus to add SDC as an experimental module is gathered in #3313520: Single-directory components in core.
Release Plan
In terms of the release schedule for Drupal 10, if this module is not included as an experimental module by May 2023 (when 10.1.0-beta1 will be released), then it will need to wait until 10.2. This will also delay the schedule for a future stable version. Normally for Experimental modules, the module gets to Beta, which triggers including it in a release as an Experimental module. Then at a later date, it becomes Stable and gets the Experimental status removed.
Roadmap for Beta (experimental status)
Here is a list of sub-issues that we currently have for that phase, all of which are must-haves to make "Beta" quality, so we can keep it as a live Experimental module in a full Drupal release:
- #3345924: Move schema validation library to require-dev
- #3345925: Fix issues reported by drupal-check
- This is a placeholder to link issues derived from a review on the MR in #3340712: Add Single Directory Components as a new experimental module.
Tasks originally proposed for this phase that made it into the patch before initial commit, or have since been finished:
- #3328636: Make schema props / slots optional
- #3328248: Allow classes and interfaces in the prop types metadata
- #3321150: [META] Increase automated test coverage
- #3320239: String props are improperly encoded/decoded
- #3319704: Allow overriding the library in the component definition
- #3319619: Restrict asset collection
- #3319616: Move components to "/components" from "/templates/components"
- #3317134: Always namespace components during usage and negotiation
- #3317173: Unable to use {% extends %} due to added code
- #3317158: Validate component props at rendering time
Roadmap for Stable
The schedule for stable release is not planned until SDC is in core as experimental.
To get this module to be ready for a stable release, here are some issues we'll need to resolve/finish, all of which are must-haves to make "Stable" quality:
- #3352256: Move code from the experimental SDC module to core
- #3352257: [SDC] Validate and improve developer experience and helpfulness of error messages
-
#3352258: [META] SDC: Improve and extend documentation
- #3352262: Create SDC "Quick start" documentation / code - We want this done by DrupalCon Pittsburgh!
- #3352272: SDC: Move the documentation from markdown to Drupal.org
- #3352260: If needed, create automated tests to validate SDC's use of Drupal escaping and Twig sandboxing
- #3352858: Move isRenderArray from SDC to Drupal\Core\Render\Element
- #3354389: Move single directory components API in \Drupal\Core\Render namespace
- #3356722: Remove schema references from contrib in SDC tests in core
- #3357382: Unable to override library auto-definition to add external CSS & JS
- #3357383: _locale_parse_js_file cannot open SDC JavaScript files
- #3365458: [Policy] SDC backwards compatibility policy
- #3385283: Components without props throw error
- #3375843: Allow other Twig node visitors to modify 'display_start' and 'display_end'
- #3365480: [SDC] Improve error handling during prop validation errors
- #3365455: Unhelpful error message with SDC when a optional variable is missing
- #3409456: Remove SDC deprecated code before 11.0.0
- #3410387: [11.x] Mark sdc as obsolete for 11.x
Non-stable-blocking issues
- Umami uses more SDC components - #3364673: [META] Create Single Directory Components for the Umami theme
- #3352261: SDC: Prevent unwanted context passing with Twig include/embed functions
- #3362132: SDC: sdc_theme_test_enforce_schema test theme contains invalid schema definition
- #3365605: [Meta] Convert core UI components to use single directory components
- Allow schema references - #3352063: Allow schema references in Single Directory Component prop schemas
- #3365682: [SDC] Add a test for multiple *.component.yml in the same directory
- Olivero uses at least one SDC component - #3364672: [META] Create Single Directory Components for the Olivero theme
- #3410389: [PP-1] Remove the sdc module from core on 12.x
- #3412295: Document deprecation in drupal.org documentation pages
Comments
Comment #2
e0ipsoComment #3
e0ipsoComment #4
larowlanI would remove the 'Claro must use at least one SDC component' from the stable list. That would require many sites to have it enabled without the option of disabling it if they weren't using it. Fine for Olivero, Umami as both of them can be opinionated.
Comment #5
e0ipsoGood point @larowlan.
Removed Claro from the list of requirements for stable.
Comment #6
e0ipsoUpdated the date to be more precise about how much time is left. About 1 month and a half to cross the finish line!
Comment #7
e0ipsoComment #8
mherchelUpdating issue summary to add the issue for Olivero to use SDC: #3347235: Create new SDC component for Olivero (tabs)
Comment #9
markconroy commentedUpdating issue summary to add the issue for Umami (theme) to use SDC: #3347672: Create new SDC component for Umami (Common Card)
Comment #10
e0ipsoComment #11
e0ipsoComment #12
mherchelAdding #3352256: Move code from the experimental SDC module to core as stable blocker.
Comment #13
mherchelAdding #3352257: [SDC] Validate and improve developer experience and helpfulness of error messages as stable blocker.
Comment #14
mherchelAdding #3352258: [META] SDC: Improve and extend documentation as stable blocker.
Comment #15
mherchelRemoving "Remove the experimental status" as a stable blocker. The plan is to fold SDC directly into core, and thus it will not be able to be experimental.
Comment #16
mherchelAdding #3352260: If needed, create automated tests to validate SDC's use of Drupal escaping and Twig sandboxing as stable blocker.
Comment #17
mherchelAdding #3352261: SDC: Prevent unwanted context passing with Twig include/embed functions as a non-stable blocker.
Comment #18
mherchelAdding #3352262: Create SDC "Quick start" documentation / code as stable blocker.
Comment #19
e0ipsoComment #20
e0ipsoAdded a follow up derived from technical review.
Comment #21
e0ipsoAdded another follow up from technical review.
Comment #22
e0ipsoComment #23
e0ipsoDedupe issue in the list.
Comment #24
e0ipsoAdded a new follow up for the class_aliases.
Comment #25
e0ipsoInitial MR has been merged. The first big step is
done.Comment #26
e0ipsoI created #3354860: Mark SDC as beta so it can be included in 10.1 to discuss marking SDC as beta stability before 10.1.0-alpha1 is tagged. This will mean that SDC will be available as an experimental module in 10.1.
Comment #27
e0ipsoThere was a video call meeting with the Front-end Framework Manager team where we went over each one of the remaining tickets. We confirmed that the tickets marked as stable blockers are indeed that, and not beta blockers.
The attendants to the meeting where:
This was documented in comment #129 of #3340712: Add Single Directory Components as a new experimental module, but referencing here for convenience.
Comment #28
dwwRemoving #3352855: Move makePathRelative from SDC to the FileSystem component which we determined is "won't fix".
Comment #29
e0ipsoAdded #3356722: Remove schema references from contrib in SDC tests in core .
Comment #30
e0ipsoI found a bug while using the beta: #3357382: Unable to override library auto-definition to add external CSS & JS. There is a workaround listed in the issue.
Comment #31
e0ipsoAdded an issue for a warning related to the locale module upon cache clears. I have only been able to reproduce this using Umami so far. #3357383: _locale_parse_js_file cannot open SDC JavaScript files
Comment #33
mherchelComment #34
mherchelComment #35
e0ipsoComment #36
e0ipsoUpdated the roadmap to add links to the meta issues to add components to Olivero and Umami, replacing the links to specific component migrations.
Comment #37
bbralaChanging target branch to 10.1.x.
Plan is to create a merge request here for 10.2.x and then create seperate issues per namespace or if needed per file so we can discuss where those classes should end up in core when the module exists experimental status.
Should probably do that here: #3352256: Move code from the experimental SDC module to core
Comment #38
mherchelAdding #3365605: [Meta] Convert core UI components to use single directory components
Comment #39
mherchelAdding #3365480: [SDC] Improve error handling during prop validation errors
Comment #40
mherchelAdding #3365455: Unhelpful error message with SDC when a optional variable is missing
Comment #41
e0ipso#3352063: Allow schema references in Single Directory Component prop schemas will require the promotion of
justinrainbow/json-schemato a runtime dependency (currently require-dev). We'll need to vet the library in #3365985: Promote justinrainbow/json-schema from dev-dependency to full dependency, and it is unclear if we want to do so.I don't think this should be a blocker for stability, but a nice-to-have. Thoughts?
Comment #42
mherchelI would love to have it as a runtime dependency. We had several folks who didn't realize that it needed to be installed for SDC to output helpful error messages. Having it as a runtime dependency would improve the DX.
Comment #43
e0ipsoAdded #3365480: [SDC] Improve error handling during prop validation errors as a stable blocker.
Comment #44
e0ipsoI think the first steps towards stability are:
Comment #45
e0ipsoAdded #3365682: [SDC] Add a test for multiple *.component.yml in the same directory as non-blocking.
Comment #46
mherchelAdding #3374901: SDC stylesheets should be added in the "theme" aggregate group (as opposed to "default" group) to correct CSS source order as a stable blocker. Discussion in Slack at https://drupal.slack.com/archives/C4EDNHFGS/p1690469220405819
Comment #47
dieterholvoet commentedComment #48
e0ipsoComment #49
e0ipsoAdded another stable blocker: #3385283: Components without props throw error
Comment #50
e0ipsoAdded another stable blocker #3375843: Allow other Twig node visitors to modify 'display_start' and 'display_end'. So great that people are trying this!
Comment #51
e0ipsoAdded another stable blocker: #3392997: SDC componentMetadata does not take the right context when a component is extended.
Comment #52
rodrigoaguileraThere is now umami SDC components so removing it from stable blockers
Comment #53
e0ipsoRemoving #3374901: SDC stylesheets should be added in the "theme" aggregate group (as opposed to "default" group) to correct CSS source order from the list. After some investigation, we notice this one is not specific about SDC.
Comment #54
e0ipsoComment #55
e0ipso#3385283: Components without props throw error is the only code issue left inside the
core/modules/sdcfolder blocking #3364672: [META] Create Single Directory Components for the Olivero theme.Comment #56
e0ipso#3385283: Components without props throw error is now fixed. One less blocker!
Comment #57
e0ipsoI don't think we can make #3364672: [META] Create Single Directory Components for the Olivero theme a stable blocker without changing Olivero's policy that prevents depending on experimental modules. My thinking is that we want to make SDC stable, and then start using it in Olivero.
Based on this I am moving it to the non-stable blocker section.
Comment #58
e0ipsoTriaging issues. I moved these (completed) items under the stable blocker section:
Comment #59
xmacinfoAny dependency between Olivero and SDC must be optional so that a user is not obligated to enable SDC just to use Olivero or take Olivero as a base theme.
Comment #60
e0ipso@xmacinfo all users will be using SDC when this issue lands. It will no longer be a module to be enabled, but something that Drupal allows, like support for postgres, Form API, or the render cache. You'll still be free to use it or not.
Comment #61
xmacinfoIf I build a theme based on the Olivero SDC variant, will I be able to override some or all SDC components included in Olivero once SDC is incorporated in Drupal (not a module anymore)?
Example:
base theme: oliveroComment #62
e0ipsoAdded a new stable blocker. This is a follow up that is 11.x only to remove some leftovers due to the BC dance.
#3409456: Remove SDC deprecated code before 11.0.0
Comment #63
e0ipso@xmacinfo correct! Take a look at the official documentation for the specific details.
Comment #64
xmacinfoOverriding an SDC component with another one makes sense.
But, actually, my question is more like:
Can I override the need for a SDC component. In other words, override SDC altogether.
For example, I create a new theme based on Olivero, but I want to use regular templates instead on a component. Can this be done or will I be locked in SDC?
If Olivero switches to SDC, will I need to create a new Olivero without SDC?
Comment #65
e0ipso@xmacinfo I think we should move this chat over to #3364672: [META] Create Single Directory Components for the Olivero theme and leave this to the stabilization discussions. Would that work for you?
Comment #66
e0ipsoAdding #3410387: [11.x] Mark sdc as obsolete for 11.x as a stable blocker.
Comment #67
e0ipsoAdding #3410389: [PP-1] Remove the sdc module from core on 12.x as a non-stable-blocker.
Comment #68
e0ipsoAdding #3412295: Document deprecation in drupal.org documentation pages as a non-stable-blocker.
Comment #70
wim leers#3352256: Move code from the experimental SDC module to core is in … does that mean this can be closed? 😄
Comment #71
e0ipsoI think the necessary follow ups after #3352256: Move code from the experimental SDC module to core have all been addressed. They were all included in #3409456: Remove SDC deprecated code before 11.0.0.
I am inclined to close this issue as well.
Comment #72
andypostDX improvement #3462156: Throw an exception if a component property's `type` contains non-string values
Comment #73
mherchelYeah, this should be closed. i'm assigning credit to everyone (I don't see any unhelpful comments), but I'll leave it to the maintainers to close.
Comment #74
mherchelComment #75
xmacinfoBefore closing for good, this ticket should link to the official SDC documentation (in a comment or a section of the IS).
Comment #76
penyaskitoDon't think we need that link (this is about changing stability, not making it into core), but here it is anyway: https://www.drupal.org/docs/develop/theming-drupal/using-single-director...
Thanks everyone!