Improve the development and workflow on Local by Flywheel and alike with devpackages

[liminalfun]

Moi!

I've been researching WP theme starters that include gulp/scss/browser-sync and are compatible with Gutenberg. So, I was really excited to test out air-light!

Issue

When I update my scss files, I don't think they are not being piped through properly. They don't appear in the live browsersync, and I don't see my changes in css/dev/global.css. I haven't been able to isolate the cause yet. I'm not sure how to best troubleshoot this, so I guess I'm asking for troubleshooting advice! Has anyone else had this issue? Perhaps there a step that I missed that would explicitly cause this issue?

If it helps, I'm using Local by Flywheel and VS Code.

Feedback
I ran into a few questions/comments in the setup process that I'd like to clarify for future users ~

1. When changing file names, I got a bit confused at first when I saw 'air-light' and 'Air-light' mentioned, but not 'Air_light'. When things weren't working for me, I tried changing 'Air_light' to my theme name and it broke everything lol. Perhaps this could be helpful to clarify in the readme?

2. When downloading devpackages, it includes a package.json file in addition to the one from air-light. Is there a process you recommend for merging them? I just manually compared and merged them (which is maybe what caused me problems).

3. In the instructions for devpackages, it was a bit unclear to me if I was supposed to add the folder 'devpackages' to the root or the files within the 'devpackages' folder to the root. I think you used language like 'extract into root' and 'add to your project folder', but that still felt a bit unclear to me.

4. There's a missing step for setting up browsersync ~ In gulp/config.js, if people aren't using dudestack, they will probably need to change the browsersync proxy settings.

Kiitos!! I hope that this feedback is helpful.

Best of luck!

[ronilaukkarinen]

Hello there! Thanks for taking the time to try Air-light and open an issue. I try to answer all the questions best I can.

We have had feedback like this before. Let me tell you a bit about Air-light. This starter theme was born after years of frustration in your company. We wanted the most lightweight starting point for our WP projects but also wanted it to have some flesh around the bones. We didn't want to go with traditional way by using old school methods and install through zips and point and click, instead we crated a set of scripts and tools that worked for us.

Over time our open source theme got more popular and we saw our scripts are not easy to understand by people in the world. So we tried to document them all. We soon noticed we cannot make this "generic" for anyone to take and use easily so we documented our tools best we can and then gave "option 2" which is practically: use any way you like, with any dev server you like. Even though we have "independent" theme on WordPress.org you can't really just install the theme and start coding on it. You need to do replaces and add gulp to be able to compile your CSS etc. etc... this is where we have a challenge to support ALL possible ways to develop this theme. Not to mention at the same time we are managing tons of updates to this theme. So we don't have one silver bullet. They come within issues like this, I hope! This is why we hope people would use dudestack and our LEMP server on mac or windows (I actually wrote a tutorial yesterday about this for Windows). I know it's too techical and not the best for everyone, but one can hope :)

If it helps, I'm using Local by Flywheel and VS Code.

Unfortunately I have little experience with Local by Flywheel with Air-light. I have tried it couple of times in the past with dudestack and it caused many problems. I'm not really familiar in what it does under the hood, so can't help you with that dev environment :( Sorry!

When changing file names, I got a bit confused at first when I saw 'air-light' and 'Air-light' mentioned, but not 'Air_light'. When things weren't working for me, I tried changing 'Air_light' to my theme name and it broke everything lol. Perhaps this could be helpful to clarify in the readme?

Yeah, namespace Air_Light; is a namespace, it acts like as it "prefixes" everything without you having to prefix each function. Namespace should not be replaced because many functionalities like nav depends on it. This is mentioned here, maybe not clear enough. air-light with dash is normal textdomain/package name for your theme, Air-light is the same with capitalization.

When downloading devpackages, it includes a package.json file in addition to the one from air-light. Is there a process you recommend for merging them? I just manually compared and merged them (which is maybe what caused me problems).

There are two tools and devpackages.

1. devpackages - For your project root. I mean the entire WordPress project, not just theme. With these you can develop your themes, plugins, all things WordPress.
2. Air-light - The starter theme tools only

BUT. package.json is different.

1. package.json inside theme directory = JS/CSS dependencies from npm
2. package.json in the root of your project = tools like gulp, stylelint, etc. that you need to run your project

So don't try to combine these two. They both have a purpose. When we start we run npm install in both root and theme dir. Then we run gulp from root dir. Theme doesn't need separate gulp inside a project.

We have separated these two because contributing and developing to the starter theme Airlight (instead of the theme it might become after replace/start script) needs its own development packages and gulp. This is sometimes confusing for users and I get that but it's necessary.

In the instructions for devpackages, it was a bit unclear to me if I was supposed to add the folder 'devpackages' to the root or the files within the 'devpackages' folder to the root. I think you used language like 'extract into root' and 'add to your project folder', but that still felt a bit unclear to me.

You are correct, it is unclear. Files included in devpackages repo go to project root, so no subfolders like devpackages there. They are part of a project. I need to clarify the README in this step, thanks for pointing this out!

There's a missing step for setting up browsersync ~ In gulp/config.js, if people aren't using dudestack, they will probably need to change the browsersync proxy settings.

Maybe, but I can't know what people are using. Some might not need our devpackages or dudestack at all, they just might install Air-light and configure their own gulps, grunts or webpacks. We just provide options.

It would be crazy to think that we'd have to support every kind of scenarios. But we at least try! However can't support them all :/ That's why Pull Requests and help are always welcome. This is what open source is for :)

I'll leave this issue open for more thoughts on how to improve the workflow with 3rd party dev environments.

[LukaszJaro]

Thanks, this came at a good time, was just installing air-light theme for the first time.

My files are not being built as well, when I make a css change nothing happens, no reload either.

Ran into issue with the devpackages not being picked up at all until I moved the files out of the folder and put them in the root directory as suggested.
Adding to that, normally my gulp/webpack is in the theme folder so I can see how this can confuse some people.

It was mentioned Theme doesn't need separate gulp yet I have a gulp inside the theme and project root, can I delete the gulp folder inside the theme? -I noticed I can run gulp inside the theme and then it changes the working directory to project root which is helpful.

Also I had to configure browsersync through config.js, I updated the proxy to my site url and I had to remove the paths for https cert and key to get it to work temporarily. I'm using laragon which generates it's own certificate I just have to point to it properly somehow.

Besides those things I thought the documentation was written very clearly.

[ronilaukkarinen]

My files are not being built as well, when I make a css change nothing happens, no reload either.

Yeah, the paths need to be set up in gulp/config.js. They are currently configured for dudestack and macos-lemp-setup.

Ran into issue with the devpackages not being picked up at all until I moved the files out of the folder and put them in the root directory as suggested.
Adding to that, normally my gulp/webpack is in the theme folder so I can see how this can confuse some people.

Yeah, like I said we want to have one gulp/webpack setup in root to manage everything under WordPress, be it plugins, themes or even templates. It's overkill to setup gulp for each occasion like a theme that is only a part of WP stack. PLUS, like I explained, there's the air-light development that is completely separate thing. People need to be able to develop Air-light only if they want to.

It was mentioned Theme doesn't need separate gulp yet I have a gulp inside the theme and project root, can I delete the gulp folder inside the theme? -I noticed I can run gulp inside the theme and then it changes the working directory to project root which is helpful.

Yes, you can delete the gulpfiles under the theme. Our startscript actually does this, see this line (btw we are completely rewriting our start script. It may be possible in the future just run cleanups/setups for other dev servers, we'll see how it goes).

Also I had to configure browsersync through config.js, I updated the proxy to my site url and I had to remove the paths for https cert and key to get it to work temporarily.

Yep, those need to be configured if you don't use dudestack or macos-lemp-setup.

Besides those things I thought the documentation was written very clearly.

Thanks! More updates regarding to the workflow is coming, at least from our perspective. I agree that using the theme should be more straightforwards also for people outside our company.

[LukaszJaro]

Found the issue @liminalfun @ronilaukkarinen

The theme path was incorrect in config.js, should be const themeDir = 'wp-content/themes/mytheme/';

https://github.com/digitoimistodude/devpackages/blob/master/gulp/config.js

Not sure if you guys are running custom directory called content?

Yes, makes sense, always thought it was overfill to have new gulp setup for each plugin or theme! -I will delete the gulp files in the theme.

Thanks for giving windows specific instructions as well, very much appreciated. I have the live reload and scripts running now. Just need to double check some other configs and make sure no more errors :)

[ronilaukkarinen]

Not sure if you guys are running custom directory called content?

Yes, our stack has everything under content and wp its own subdir, and more. See the docs.

Thanks for giving windows specific instructions as well, very much appreciated.

No probs! Unless I didn't already mentioned before (lack of sleep - no short memory!) I have actually written a comprehensive tutorial on how to install LEMP server, dudestack and Air-light on Windows, released on Sunday, check it out. Tested out it myself and my friend also got successfully Air-light up and running.

[LukaszJaro]

I was also running into style-lint error, just had to modify the path in .stylelintrc

"importFrom": [
        "wp-content/themes/mytheme/css/dev/global.css"
      ]

Thanks, that makes sense why content is being used throughout.

That's a great and very through article you wrote! Here's the thing, many will not want to build there servers from scratch and prefer to use there own environment and tools(we can all agree on visual studio code).

You mentioned xampp or mamp, they are very slow and clunky, I use laragon(https://laragon.org/). It's very fast, has one click install options for WordPress, which also installs php, mysql DB, etc, It automatically edits the windows host file for you and puts in correct entry. You can switch php/mysql versions easily. You can add extensions easily, has a mail catcher, creates https certs, has a terminal, reloads server with the click of a button..the list goes on.

Thanks to this thread, I wouldn't of got this far haha.

[ronilaukkarinen]

Yes, indeed, stylelintrc need to have right path as well. These are not very well documented for previously mentioned reasons. Glad you got it working!

We could open a Wiki for these things and if you want you could even contribute in form of writing guides for laragon. I have never heard of laragon before but it sounds interesting! We use only macs so I guess no need for that but I keep it mind next time if for some reason need Windows for development. Although I'm a guy that never liked GUI software in development. I understand everyone is not like me but there should always be an option to dive deep :)

Let's keep this discussion open so that we can improve Air-light workflow on other platforms!

[ronilaukkarinen]

@LukaszJaro FYI: There is now added laragon-support in 7.1.4. This release adds a bash script meant for laragon. Implemented and tested by @divn.

Would @liminalfun be up for experimenting such starting script for Local by Flywheel? This is a very low priority for me since I'm macos-lemp user but I could try to set it up on later time.

The issue will stay open until we have proper support for top 3rd party development environments like Local 🙂 .

[LukaszJaro]

That's cool! Noticed also a more detailed wiki with laragon, nice and thanks! -will test out soon.

[ronilaukkarinen]

I'm going to close this because of inactivity. Everything you need to get going with Laragon or Local by Flywheel can be found in the wiki. If you have ideas on how to contribute to the 3rd party dev env workflow, please let us know. We can open the discussion again when necessary.