Design and implement new module asset directory structure and naming in A3

As we punch ahead through a3, we’ve started talking through some of our well-established naming conventions, and want to surface the following two proposals for open discussion.

Pushing Assets to the Browser Automatically: Scenes vs Builds

The good news is that A3 pushes assets to the browser automatically if you put them in the right folder in any Apostrophe module. This is a nice win over A2, where you had to call pushAsset for each one.

But, we’d like your input on how to name these folders.

We’ve considered both this:

// browser js for all users, example: widget player
lib/modules/articles-widgets/builds/everyone/player.js
// vue components to register for apostrophe admin UI
lib/modules/articles-widgets/builds/user/components/*.vue

And this:

// browser js for all users, example: widget player
lib/modules/articles-widgets/scenes/everyone/player.js
// vue components to register for apostrophe admin UI
lib/modules/articles-widgets/scenes/user/components/*.vue

We like the name “builds” because it’s clearly about building assets for the frontend.

We like the name “scenes” because it relates to Apostrophe’s internal concept of an asset “scene”. But, we’re thinking of renaming that concept “builds” altogether.

You’ll also note that the rules for /user are a little different from /everyone. Because Apostrophe’s admin UI is built on Vue, we provide a specific folder to automatically register Vue components from any module. We have other special folder names as well. /everyone is different: any .js files directly in that folder simply get pushed all the time, as part of the bundle for site visitors or editors.

Your input is welcome!

Singular vs Plural: Singularizing our module names

For a long time now we have had plural names for modules that manage many instances of something. For instance, an “articles” module that extends pieces might manage thousands of articles, so we gave the module a plural name. It seemed like a good idea, but in practice it has caused a lot of confusion. When is a module singular, and when is it plural? If it takes more than a second to explain, it’s not really helping.

So even though we are very far along with 3.x and the change is a little bit challenging, we are looking at moving to strictly singular module names. Here are some examples of the change we’re talking about, as folder paths, so you can visualize it in the context of a project:

lib/modules/articles —> lib/modules/article
lib/modules/events —> lib/modules/event
lib/modules/apostrophe-pages —> lib/modules/@apostrophecms/page
lib/modules/articles-widgets -> lib/modules/article-widget

We think this will be less confusing in the long run, but we would love to get your input before we make this change.

A special case: there are a few modules in Apostrophe that are never actually “instantiated” (you don’t turn them on in app.js, and we don’t turn them on in defaults.js). These modules are “abstract base classes:” you extend them to make your own modules. For these, we already made the change to add -type to the name:

lib/modules/apostrophe-pieces --> lib/modules/@apostrophecms/piece-type
lib/modules/apostrophe-widgets --> lib/modules/@apostrophecms/widget-type

[boutell]

Cool, I think that could work out:

“Apostrophe’s APIs are totally RESTful out of the box. The URL of the API matches the name of the module so that our UI code can always find it. Note that our module names are singular, so the API URLs are singular too. Want the API to be available under an additional name, such as a collective or plural noun, or simply at some other URL than /api/v1/your-modulename? Set the restAlias option for the module, and both URLs will work.”

Is this a story everyone is comfortable telling?

On Tue, Jul 14, 2020 at 3:26 PM Greg van Brug [e-mail] wrote:

Greg, are you suggesting the API URL should be plural but the module singular? If it’s not equal to the module name, pushing out code that knows what to talk to automatically gets a lot harder.

Yes, I was suggesting a singular module name and a plural API endpoint following REST conventions. I didn’t really think there was a tie between the two but I oof, yea, can see how that would make things complicated. I still would prefer singular modules, but if the API URLs defaulted to singular and we had a restApiAlias, I might just configure the URLs myself if I was going full headless.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/apostrophecms/apostrophe/issues/2244#issuecomment-658368462, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAH27ORSONIOU5LKJHASKDR3SWPHANCNFSM4OZT2OBQ .

–

THOMAS BOUTELL | CHIEF TECHNOLOGY OFFICER APOSTROPHECMS | apostrophecms.com | he/him/his

[falkodev]

In 3.x we already decided that the name option of a piece module should default to the module name so nobody ever has to think about setting it again, which would currently put a plural word in the type property of a single thing in the database. Although that’s not a big deal, I like how going to all singular module names ties off that loose end.

Love singular. Consistent with REST convention (even though it is not related). I have the habit of having singular folders names for my personal Apos projects.