Generating gulp setups for TYPO3 with Yeoman

Generating gulp setups for TYPO3 with Yeoman

Philipp Nowinski 24. Februar 2015 Expert Topics

0 Kommentare // Lesezeit: 8 min.

In the last two blogposts I talked about what gulp is, why we wanted to integrate it into our frontend workflow and how we got rid of compass along the way. Now it's time to put the pieces together. Today I want to show you how we set up gulp for our TYPO3 projects.

Say hello to the Yeoman

The first thing that hit me when I started to think about how a potential setup could look like, was the fact that we needed some kind of boilerplate. Since we are an agency, new projects come in quite often, so it would make sense to maintain the gulp setup in an independent codebase, that you can pull in every time you start a new project. Also, setting up a new project should be as quick and easy as possible. And there is the perfect tool for this kind of job: it's called Yeoman!

Yeoman is a tool that allows you to run so called generators, to quickly scaffold new projects. There is already a ton of generators out there that you can install and it's pretty easy to write your own. I highly recommend checking it out. You can install yeoman via NPM. To do so, run

npm install -g yo

This will make the 'yo' command available on your system. Yeoman generators can also be installed via NPM and are prefixed with 'generator-'. To see what's out there, you can check out the list on their official website: http://yeoman.io/generators. There already are a lot of great generators, including a 'generator-generator' to scaffold your own Yeoman generator. Pretty neat, right? :-)

Installed generators can be invoked by running:

yo generatorname

But that won't work for our setup. We don't have just one assets folder we can point gulp to, but a bunch of extensions which all have their own assets. So we need to tell gulp where it can find the scss files we want it to compile. To do so, we can pass it the name of the extension we want to work on with the --ext parameter. So our command needs to look something like this:

What exactly will it do for you?

So, what exactly happens when you run a generator? Basically, it will ask you a couple of questions and then copy some boilerplate files over to your project directory, according to you answers. It's also possible to use a templating mechanism inside the boilerplate files, so the generated output can be deeply configurable. Because of that, generators tend to become very opinionated. So if you can't find anything that fits your needs, you should consider writing your own. It's also possible to call other generators from within your generator. So you could e.g. write a custom generator, that at some point calls another generator that is already out there. You can read more about this in the Yeoman documentation.

Introducing generator-gulp-sgalinski

After going through the list of available generators, we found that there is very little TYPO3 related stuff and nothing that would fit our needs. So we wrote our own generator. It is called generator-gulp-sgalinski and, naturally, it is OpenSource. So check it out, tell us what you think about it and please feel free to use it on your own projects. Furthermore, if you've got any ideas on how we could improve the current version, or if you encounter bugs, just get in contact with us. We'd love to chat about this :-).

What's in there?

Now let's finally take a look at what generator-gulp-sgalinski can do for you. The first question it will ask you is what kind of project you want to build. There are basically two different kinds of projects: standalone and TYPO3. The standalone project is mainly meant for scaffolding prototypes and anything that lives without a backend. But for this article, let's take a closer look on the TYPO3 projects.

Our projects are almost completely organized in Extbase Extensions. Therefore, the generator is split into two different setups.

The project root

The first thing we will need to generate is the gulp setup inside our projects root. We can do this by going to our projects root directory and running

yo gulp-sgalinski

When the generator asks to specify the project type, we will answer 'TYPO3 Frontend Setup'. It will then ask some more questions about what we want to include in our project, before it finally generates the necessary files and installs all dependencies.

Depending on our answers, we will get the following:

.editorconfig

This is the configuration files for Editorconfig. If you don't now it, you should check it out. It's a quite handy way to share configuration for texteditors and IDEs project wide.

.jshintrc

This file is where we can declare our own rules for the jshint task. If your IDE supports jshint, chances are that it will automatically read the settings from this file as well, or that you can at least configure it to do so.

bower.json

If you chose to use Bower for frontend dependency management, this is where the dependencies will be declared.

package.json

This is where all node dependencies are declared (this includes gulp and all gulp-plugins).

The gulp directory

This directory is where our gulp tasks live in. There is one JavaScript file for each task and a settings.js file. The settings file handles the path information for our assets. We'll cover that in a minute.

gulpfile.js

This is the entry point for the gulp setup. It defines the default task, as well as the watch task and includes all the tasks from the gulp folder.

The extension folders

We've got gulp set up now, but there is nothing to run a task on, yet. The files we want to work on live inside their extensions folder, so we need to do one more thing. Inside every extensions folder we want to work on, we need to run the generator again. This time we pick 'TYPO3 Extbase Extension' as the project type. The generator will ask some questions about the paths to the extensions assets and then generate a asset-path.json file. This file will tell gulp where to find the files we want to work on when we run a task. Since different extensions can have different paths to their assets, this is an important step.

Let's gulp

Now, this is where it gets interesting. There are two different ways of running a task. We can run a task through a watcher, when we change a watched file, or we can invoke a task manually.

Doing it manually

Let's first have a look at invoking tasks manually. To run the css task, you usually would run:

gulp css

But that won't work for our setup. We don't have just one assets folder we can point gulp to, but a bunch of extensions which all have their own assets. So we need to tell gulp where it can find the scss files we want it to compile. To do so, we can pass it the name of the extension we want to work on with the --ext parameter. So our command needs to look something like this:

gulp css --ext acme_base

Gulp will then read the asset-paths.json file we've put into the acme_base extension folder which will tell it exactly where to look for the scss files and where to put the compiled css.

Using the watch task

During development, you usually do not want to invoke the css task manually every time you've made a change, but use a watcher instead. So let's just run the default task.

gulp

The default task will start a BrowserSync  instance and open it up in your web browser. If you are not familiar with BrowserSync, you should definitely check it out. It basically is an improved version of Livereload that will also synchronize key- and touch-events and offers some more really handy tricks. The generator will configure BrowserSync to point to the URL you specified during the project generation and will also add the query string parameters 'no_cache=1' and 'disableScriptmerger=1' to each request. The first parameter disables the TYPO3 frontend cache, so you always get a fresh version of the site while developing. The second parameter disables the scriptmerger extension for TYPO3. We use this extension on every project for merging and compressing JavaScript and CSS before sending it to the client. But that's something we don't want during development since it would disguise the information about the original source files.

Gulp will watch all .js and .scss files inside typo3conf/ext. So whenever you change a file that matches this pattern, it will trigger the corresponding gulp task for the relevant extension. We don't need to specify an extension name this time, because gulp can get this information from the path of the changed file.

Check it out

So that's how our new frontend toolchain looks like. If you are interested in how this looks under the hood, you can check out the code on our Gitlab instance. And as I said earlier, if you feel like you've got anything to contribute, feel free to get in touch. For now we are pretty happy with our new setup, but as always, there is still room for improvement and many ways to develop this further. And we've already got some ideas on what the next version could look like.


0 Kommentare

Dateien hier ablegen
Dateien hochladen
Keine Kommentare.